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1 - Introduction and Editor 



Introduction 


GFA-BASIC Version 3.0 puts an extensive programming language with a 
comfortable development environment at your disposal. 

Program control is of great importance in modem programming languages. 
The Editor supports structured programming by automatically indenting com¬ 
mands within loops and conditions. In addition to this, subroutines in program 
listings can be replaced by a symbol. Through a simple keystroke the sub¬ 
routine can be "collapsed" at its present position. In reference to the condition¬ 
al instructions IF-ELSE-ENDIF, additional commands are available giving 
greater flexibility (ELSE-IF, SELECT-CASE). 

Procedures and Functions make it possible to formulate subroutines. The 
value of a variable as well as the variable itself can be passed between these 
subroutines. Furthermore, in addition to the normal loop commands: FOR 
NEXT, REPEAT UNTIL.WHILE WEND and DO-LOOP expanded loop com¬ 
mands have been included: DO UNTIL, DO WHILE, LOOP UNTIL, and 
LOOP WHILE. Direct access to operating system routines makes it possible to 
program in close relation to the system. Many of these functions are present in 
the form of simple commands. Assembler and C subroutines can be included 
with commands such as RCALL, C: and MONITOR. 

Amiga screens and windows can be opened and managed through extremely 
simple commands. The GFA-BASIC 3.0 Interpreter makes use of true integer 
arithmetic, which offers extremely high calculation speed, as well as floating 
decimal point arithmetic, which offers extremely accurate calculations (13 
decimal places). Commands for bit manipulation (BCLR, BSET, BTST 
BCHG, SHL, SHR.OL, ROR, etc) as well as an extensive array of variable 
types are also present 
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Working with the handbook 


First a short explanation of the handbook followed by an introduction to the 
interpreter. 

Following are the descriptions of the Editor commands. The following chap¬ 
ters contain a more detailed explanation of the commands and functions of 
GFA BASIC 3.0. These sections are divided into specific applications. An al¬ 
phabetical index of all commands and functions, with their corresponding 
locations in the handbook can be found in the appendix. 

The command description is constructed as follows: 

- Command syntax 

- Description of the allowed parameter types 

- Command explanation 

- Example 

Optional parameters in the syntax are marked by square brackets, for example; 
LEFT$(a$[,x]) 

There are Commands and Functions in GFA-BASIC. Commands return no 
values. 

LINE 100,100,200,200 

Functions return a value, this value can be displayed with PRINT, assigned to 
a variable or used in an expression. For example: 

PRINT ASCC65’) 

PRINT ASC(-A') 
a = ASC(*A") 
b = ASC('A') + 32 
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Working with the handbook 


It is not possible to determine whether a function will return a value solely by 
the syntax used in this handbook, this can only be determined by the descrip¬ 
tion of the function itself. For example ASC(a$) is simply given as syntax. Op¬ 
tional parameters that may contain any number of items (DATA for example) 
will be enclosed in brackets; these brackets will contain two items followed by 
three periods, for example: 

DATA [x,y,...] 

The parameter types allowed can be found under the syntax description. The 
following abbreviations will be used: 

avar arithmetic variable. A numerical variable must be used with this type of 
parameter. 

aexp arithmetic expression. This is any expression that produces a number. It 
can also be a constant (a number) or a variable (variables are a part of 
an expression). Examples of arithmetic expressions are: 
a% 

3 

2+a%+ASC("A") 

svar string variable. These are character strings. This type of variable has an 
ending of $. 

sexp String expression. This is any expression which produces a string. This 
can also be a constant (text in quotation marks) or a string variable. Ex¬ 
amples of string expressions are: 
a$ 

"Test" 

a$+"Test"+LEFT$("MANUAL”,4) 
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Working with the handbook 


ivar whole number variable (integer variable) 
iexp whole number expression (integer expression) 
bexp logical expression (boolean expression) 

It is important to know that not just any numerical parameter can be used in 
some types of variables. The most important example of this are addresses. 
Addresses must be given in a variable at least 4 bytes long; Boolean, Byte, or 
Word variables are, therefore, not allowed. An explanation of the command 
will follow the description of the parameter types allowed. The meaning of the 
command and its individual parameters will be explained thereafter. 

The explanation of a command will end with one or more examples. Every ex¬ 
ample can be entered in the editor and started with RUN (shift+FlO or clicking 
on RUN in the menu list). The effect the example creates will then be ex¬ 
plained. 

This concept will be followed throughout the handbook with the only excep¬ 
tion being in the operating system section. In this section the name of the func¬ 
tion will be followed by a short description of its function. 

The manual closes with a collection of tables and an alphabetically sorted list 
of all commands and their corresponding page numbers in the handbook. 
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First steps with GFA-BASIC 3.0 


This section is for those users of GFA-BASIC 3.0 who have no previous ex¬ 
perience with this programming language. Those who have previously worked 
with the ATARI versions can skip this section. 

The GFA-BASIC 3.0 program disk is not copy-protected. You should therefore 
make a back-up copy of the original disk before doing anything else. You will 
find instructions for copying the disk in your computer owners manual. Now 
put the copy of the program disk in the disk drive and start the GFA-BASIC 
Interpreter. 

The editor in which you can create your programs will now appear on the 
screen. Enter the following program lines and press the RETURN key after 
each line. You do not need to type the spaces in front of some of the lines. The 
indentation of the lines is carried out automatically by the editor. You do not 
need to pay attention to case, upper or lower, while entering a line either; when 
you end a line with return the case will automatically be set by the editor. 

OPENW 0 
REPEAT 

WHILE MOUSEK=1 

BOX MOUSEX,MOUSEY, MOUSEX+30.MOUSEY+30 
WEND 

UNTIL MOUSEK=2 

You will find the word RUN in the upper right comer of the screen. Point to 
this word with the mouse arrow and click the left mouse button to start the 
program. A window will be opened on the Workbench screen. Now if you 
press the left mouse button and move the mouse around the desk you can draw 
within the window. 

A square is used as the "brash". Pressing the right mouse button ends the 
program. An Alert-box will appear on the screen with the message "Program 
End". Point to the word "Return" in this box and press the left mouse button. 
You will now find yourself in the editor. 
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First steps with GFA-BASIC 3.0 


How does this program function? The drawing is done with the PBOX com¬ 
mand in the middle of the program. This command draws filled squares. The 
four parameters give the comer points for this square. The variables 
MOUSEK, MOUSEX, and MOUSEY contain information about the mouse. 
MOUSEK returns the mouse button pressed, MOUSEK=l means the left 
mouse button has been pressed and MOUSEK=2 means that the right mouse 
button has been pressed. MOUSEX and MOUSEY return the position of the 
mouse arrow in x and y coordinates. 

The rest of the commands (REPEAT, WHILE, WEND, UNTIL) are loop com¬ 
mands. The loop from the command WHILE MOUSEK=l and WEND is the 
equivalent of "repeat, as long as the left mouse button is pressed". Because 
there is no command following the UNTIL command the program will end 
after the exit from the REPEAT-UNTIL loop. 

Now go to the last line of the program and type the following incorrect 
program line which is missing the letter I in the command PRINT: 

PRNT'Tesf 

When you press the return key to confirm the command and to enter the line 
you will hear a tone and the second line in the editor will have an error mes¬ 
sage stating Syntax Error. 

As you can see the Editor checks for syntax errors during the development of 
the program. Go to the letter r with the cursor and press the Delete key three 
times. The line now reads: 

p "Test' 

Pressing the RETURN key will leave the line, the letter P will be recognized 
as the command word for PRINT. 
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The Editor 


The editor in GFA-BASIC 3.0 is not a typical text editor. It is in fact, especial¬ 
ly designed for the development of programs. This is shown by the fact that 
syntax errors are found during the creation of the program itself. In addition to 
this, commands in loops are automatically indented and command abbrevia¬ 
tions are changed to their actual names (for example "p" into PRINT). 

When a program is being written the syntax of each line is checked each time 
you try to leave the line. If the syntax of the line is not correct then an error 
message appears on the second line of the editor stating "Syntax Error". The 
line cannot be left until the error is removed. It is possible to leave an incorrect 
line by placing a remark character (’) at the beginning of the line. Each 
program line can contain only one command. Remarks can be placed after the 
commands. This single command cannot be more than 255 characters long. If 
a line becomes longer than 80 characters the beginning of the line will disap¬ 
pear and this line will be scrolled horizontally. 

When leaving a line a syntax control check is made and the correct indentation 
and format for the line are set This includes the removal of excess spaces (for 
example 2 + 2 becomes 2+2) and command and variable names are put into 
their proper case. 


1 -8 


GFA-BASIC 3.0 Amiga 




The cursor keys 


The cursor movements can be carried out using the cursor keys. The cursor 
keys have the following meanings: 


left arrow —» 
right arrow -» 
up arrow —> 
down arrow —» 


Move cursor one letter to the left. 
Move cursor one letter to the right 
Move cursor one line up 
Move cursor one line down 


The movement of the cursor has some limitations. It can be at most one 
character beyond the last character on the line and at most one line past the last 
program line. When the cursor is moved to a line that is shorter than the line it 
was on, it will move to the last character on the shorter line. Otherwise it will 
remain in the same column it was in previously (This is a change from the 
editor of the older versions of GFA-BASIC). It is also possible to reposition 
the cursor with the mouse. To do this the mouse arrow is placed where the cur¬ 
sor is to be placed, and the left mouse button is clicked. 

When the Insert key is pressed, a blank line will appear above the line present¬ 
ly containing the cursor if there was no change made to that line. The cursor is 
placed at the beginning of this empty line. Clr/Home moves the cursor to the 
upper left comer under the menu List, Control+Clr/Home jumps to the begin¬ 
ning of the program listing. 

With the Alt+Help key combination, changes to a line can be undone as long 
as the cursor is still on the line that was changed. The HELP key alone makes 
it possible to Hide and Unhide procedures. 

With this we mean that when the cursor is on a line which contains the word 
PROCEDURE and the HELP key is pressed the lines up to the next RETURN 
will disappear and be replaced by an arrow ">" in front of the PROCEDURE. 
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The cursor keys 


In this case it is not possible to make changes to the procedure name or the 
parameter list of the subroutine. In order to make the command lines between 
PROCEDURE and RETURN appear once again the cursor must be moved to 
the line containing the word PROCEDURE and the Help key pressed once 
again, or the arrow in front of the line may be deleted. 

This "hiding" of a subroutine makes short overviews of the program listing 
possible, in which only the subroutine that is being worked on at the time is 
visible. A program with "hidden subroutines" may look like the following ex¬ 
ample: 

init 

main_menu 

> PROCEDURE init 

> PROCEDURE main_menu 

> PROCEDURE menujist 

> PROCEDURE load 

> PROCEDURE save 

> PROCEDURE edit 

> PROCEDURE getjnfo 

> PROCEDURE showjnfo 

With one of the procedures unhidden the program would look like this: 

init 

main_menu 

> PROCEDURE init 

> PROCEDURE main_menu 

> PROCEDURE menujist 
PROCEDURE load 

FILESELECT "-Load FileYOk*,file$ 

IF NOT EXIST(file$) 

ALERT 0,’File does not exist!’, 1,'Abort*,r% 

ELSE 

OPEN T,#1,file$ 

RECALL #1,da$(),-1,x% 

CLOSE #1 
ENDIF 
RETURN 

> PROCEDURE save 

> PROCEDURE edit 

> PROCEDURE getjnfo 

> PROCEDURE showjnfo 
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The numeric keypad 


The numeric keypad is normally used for entering numbers and a couple of 
other characters. These keys can also be used in combination with the CON- 
TROL-key. Their meanings have much the same meaning as when the NUM- 
LOCK function is turned on (For example with PC’s). Their meaning is: 


CONTROL and 4 
CONTROL and 6 
CONTROL and 8 
CONTROL and 2 
CONTROL and 7 
CONTROL and 1 
CONTROL and 9 
CONTROL and 3 
CONTROL and 0 


Jump to start of line 
Jump to end of line 
Page up 
Page down 

Jump to start of program 
Jump to end of program 
Page up one page 
Page down one page 
Insert a line 


The numeric keypad can also be turned into a mode in which it is no longer 
necessary to use the combination of the CONTROL key and the number. In 
order to set this mode press CONTROL and [Num Lock) in the numeric 
keypad. 

Now when one of the numeric keys is pressed it will react as if it had been 
pressed in combination with the Control key. 
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Control commands 


Many of the CONTROL commands are already explained in other chapters of 
the manual. These commands and many others which were not named will be 
explained there (with the exception of the control commands used in combina¬ 
tion with the number keypad). 


CONTROL+Y 

CONTROL+U 


CONTROL+N 


CONTROL+Q 

CONTROL+B 

CONTROL+K 

CONTROL+R 

CONTROL+C 

CONTROL+E 

Shift+CONTROL+E 

CONTROL+F 
Shift+CONTROL+F 
CONTROL+c ursor left 
CONTROL+cursor right 
CONTROL+cursor up 
CONTROL+cursor down 
CONTROL+Home 
CONTROL+Z 
CONTROL+Tab 
CONTROL+G 


erases the line the cursor is currently on 
undelete replaces the last line that was deleted 
with CONTROL+Y. This serves as one way to re¬ 
store a line erased accidentally. It can also be used 
to copy or move a line (for example to copy a line 
press CONTROL+DELETE and then control+U 
twice; you will replace the original line and make 
an extra copy). 

places an empty line above the command line 

containing the cursor, even when a change has 

been made to the current line 

Call Block Menu item (Same as Function key F4) 

marks the beginning of a block (Block) 

marks the end of a block (Block) 

page up one page 

page down one page 

replace 

replace, with prompt for search and replace 

strings. 

find 

find, with prompt for the search string 

jump to the start of the line 

jump to the end of the line 

page up one page 

page down one page 

jump to the start of the program 

jump to the end of the program listing 

jump one tab position to the left 

opens the line number field for the input of line 

numbers (the cursor will jump to the line entered). 
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More Editing keys 


A special group of CONTROL commands make it possible to set and jump to 
marks within the editor. These marks apply to the editor only and have nothing 
to do with GOTO or RESTORE. These marks can be set at the cursor position 
by pressing CONTROL and a number key between one and eight on the main 
keyboard. The cursor can be repositioned later by pressing the ALTERNATE 
key and the corresponding number key. These marks are only used by the 
editor, and should not be confused with the labels associated with GOTO or 
RESTORE. 

The key combinations Altemate+7-9 and Altemate+O are preassigned 
however. Pressing Altemate+7 makes the cursor jump to the last cursor posi¬ 
tion before a program was run, or before the screen was changed to direct 
mode. Altemate+8 jumps to the position the cursor was at, at the time the 
editor started. With Altemate+O the cursor will jump to the last cursor position 
at which a change was made. Altemate+9 jumps to the position at which the 
last string search was executed. 

By using the DELETE key the character the cursor is on can be deleted. The 
rest of the line will then move to the left to fill the empty space. The Back¬ 
space key will erase the character to its left and the rest of the line will follow 
it. 

Pressing the Tab key will move the cursor to the next tab position to the right. 
The tab positions are set eight characters apart CONTROL+Tab moves the 
cursor to the next tab position to the left. 

The RETURN and ENTER keys move the cursor to the beginning of the next 
line. When the ESCAPE key is pressed the screen will change to direct mode. 
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The menu lines and the function keys 


The top two lines of the editor contain two menu lines. The AMIGA symbol 
can be found to the far left of the top line. When this symbol is clicked on a 
pull down menu is activated. A clock is found at the right edge of the screen 
with the current line number displayed directly under it The operation of both 
of these menu items will be explained at the end of this section. 

There are twenty command words between the Amiga symbol and the clock, 
stacked in pairs of two, which can either be activated using the mouse or the 
associated function key. The lower line can be activated by simply pressing the 
appropriate function key while the commands in the upper line can be ac¬ 
tivated by pressing the Shift key and the appropriate function key. 

The function key FI corresponds to the command word "LOAD" and the 
Shift+Fl combination corresponds to the command word "SAVE". 

The Menu items have the following meanings: 

Load (FI) 

The Load command makes it possible to load a GFA-BASIC 3.0 program. The 
format employed here uses command tokens. Files using this format can be 
loaded and saved very quickly. Normally the file extension .GFA will be used 
when files are saved in this format. 


Save (Shift+Fl) 

A file selector box will appear in which a name can be entered. The program 
that is presendy in the editor will then be saved under this name. It will be 
saved in the tokenized format explained under Load. The extension will again 
be .GFA. The extension will be set automatically if not set by the user. If a file 
with this name is already present it will be saved with the extension .BAK. 
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The menu lines and the function keys 


Merge (F2) 

With this command, data in ASCII format can be merged directly into the cur¬ 
rent program. The data is merged into the program starting with the line in 
front of the cursor. The extension for this type of ASCII data is .LST. 

—> Program lines with this symbol indicate the lines 
—> the editor cannot interpret 

Save,A (Shift+F2) 

The current program can be saved in ASCII format using Save,A. A program 
saved in this format can be loaded later using Merge. The file extension will 
be .LST. This extension will be set automatically if no extension is given by 
the user. 

If a file with this name already exists it will be saved with the extension .BAK. 
Llist(F3) 

This command controls the printing of the program listing currently in the 
editor. The format of the listing can be altered through use of so-called point 
commands. These commands are entered into the program listing as normal 
commands. They are (x is a place holder for a number): 


.11 XX 

Maximum line length 

.pi XX 

Maximum page length 

. ff XXX 

Form-feed-character 

(For printers that have other values for form feed the 
appropriate values can be entered. The default is .fP012) 

.he head 

Text for the header line 

.fo foot 

Text for the footer line 

.lr xx 

Left margin 

.in xxx 

(Printer) initialization, a string that will be printed only 
once at the beginning 
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The menu lines and the function keys 


.1- This instruction will suppress the printing of the lines 

following. The listing can be resumed later by using .1+. 

.1+ Resume printer output 

.nl to .n9 Turn on line numbering with 1 to 9 places 

.nO Turn off line numbering 

In the text of the Header and Footer lines the following special characters can 
be inserted: 

\ xxx Characters with the ASCII code xxx 

\ D Date 

\ T System time 

# Page number 

In order to use the special characters # and \ in the output a second \ must be 
entered. The character combination \\ will print \ on the printer, \# will 
produce #. 

Quit (Shift+F3) 

Makes it possible to leave the GFA-BASIC Interpreter. 

Block (F4) 

When no block has been marked and this menu item is chosen then the text 
"Block ???” appears in the menu list to indicate that the menu item is useless 
in this situation. If, however, a block has been marked, then a menu will ap¬ 
pear on the top line of the editor. The commands of this menu can be activated 
by clicking on it with the mouse pointer or by pressing the corresponding com¬ 
mand letter. 
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The menu lines and the function keys 


The menu items are (The command letter that will activate each item is in 
parenthesis): 


Copy (C) 

Move (M) 

Write (W) 
Llist(L) 
Start (S) 
End (E) 
A Del 
Hide (H) 


Copies the block at the current cursor position. The marked 
block remains marked. 

Moves the block to the current cursor position. The block mark¬ 
ing is removed. 

Saves the block as an ASCII data file. 

Prints the block to the printer. 

Jumps to the start of the block. 

Jumps to the end of the block. 

Deletes the block. 

Removes the block marking. 


Pressing any other key (or the mouse button) will remove the block menu. 


New (Shift+F4) 

Erases the current program in the editor. 


BlkEnd (F5) 

With BlkEnd the line above the cursor can be marked as the end of a block. If 
a line has already been marked as block start and is above the BlkEnd then the 
marked block will be shown in a different color. This command can also be ac¬ 
tivated by pressing CONTROL+K. 
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The menu lines and the function keys 


BlkSta (Shift+F5) 

With BlkSta the line the cursor is on will mark the start of a block. If a line 
below this line is marked as block end the block will be shown as described in 
BlkEnd description. This command can also be activated by pressing CON- 
TROL+B. 

Find (F6) 

After activating the Find command, the text to search for can be entered. The 
search begins with the line that the cursor is presently on. This search can be 
repeated without reentering the search string by pressing CONTROL+F or 
CONTROL+L. 

If the search string is found, the cursor will be at the beginning of the line con¬ 
taining the text. If it is not found, the cursor will go to the end of the program 
listing. 

When the Find instruction is called again the text previously searched for will 
appear in the line used to input the search string. The following editing func¬ 
tions exist to help input a new search string: 

Cursor left Cursor moves one character to the left (as long as it is not 

to the far left already). 

Cursor right Cursor goes one character to the right (as long as it is not 

at the end of the search string). 

Delete Erases the character within the search string that the cur¬ 

sor is presently on, the rest of the search string fills in 
from the right to the left 

Backspace Erases the character to the left of the cursor (as long as 

the cursor is not to the far left) and pulls the rest of the 
search string along with it 
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Escape Erases the Input field. 

Retum/Enter Accepts the search string and begins the search. The find 
command can also be invoked with the key combinations 
Shift+Control+F or Shift+ Control+L. Strings in "folded" 
procedures (see Help key in the Cursor key block sec¬ 
tion) will not be found. 


Replace (Shift+F6) 

This command serves to replace specific text with other text First, the text to 
be replaced is requested. Then the text to replace it with is asked far. The 
program listing is searched beginning with the current cursor position and, if 
the desired text is found, the cursor jumps to the beginning of the line contain¬ 
ing the search text. 

The text can be replaced by pressing CONTROL+E. Pressing this key com¬ 
bination again will continue the search, or replace a second search string if it is 
on the same line. 

The Replace command can also be called through the key combination 
Shift+CONTROL+E. The editing possibilities available with search and 
replace were described in the Find command description. In "hidden" proce¬ 
dures (see Help Key in the Cursor key block) no text will be found. 


Pg Down (F7) 

Scrolls downward through the program text one screen at a time. This can also 
be done with the CONTROL+C key combination. 
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The menu lines and the function keys 


Pg Up (Shift+F7) 

Scrolls upward through the program text one screen at a time. This can also be 
called using the CONTROL+R key combination. 


Insert/Overwr (F8) 

Switches between Insert mode and Overwrite mode. Insert mode moves 
characters to the right Overwrite mode replaces the character under the cursor 
with the new one entered from the keyboard. 


Interl/Normal (Shift+F8) 

In "Normal" mode the editor screen will contain the "Hires" resolution in¬ 
dicator. In this resolution 28 lines can be shown. In "Interl" mode "Hires-Lace" 
indicator is displayed, and a slight flickering of the screen on normal monitors 
occurs. In this mode 57 lines can be shown. These modes can be switched be¬ 
tween Interl/Normal. 

ClkOn/CIkOff (F9) 

The clock display can be turned on or off with this command. 

Direct (Shift+F9) 

This command calls the direct mode. In this mode GFA-BASIC commands 
can be entered and will be executed directly when the RETURN or ENTER 
key is pressed. Some commands, loop commands for, example, are not usable 
in direct mode. This mode can also be invoked using the Escape key. 

It is also possible to repeat the last eight commands (entered in direct mode) 
using the "Cursor up" and "Cursor Down” keys. 
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The menu lines and the function keys 


Pressing Alt+Help will show the last command. With the key combination 
Control+Cursor left or Control+Cursor right the end and beginning of the line 
can be reached. It is also possible to switch between Insert and Overwrite 
modes by pressing the Insert key. 

By pressing the Escape key, followed by Return, the screen will return to the 
editor. An alternative to this method is to press Control+Shift+Altemate simul¬ 
taneously. 

In order to use this instruction for more than one line at a time a procedure can 
be written in the Editor that contains this command. This procedure can then 
be called from the direct mode. 

Test (F10) 

When this key is pressed, all loops, and subroutines within the program are 
checked to make sure they are properly closed. A structure check is also per¬ 
formed. 

Run (Shift+FlO) 

Starts the program currently in the editor. If this program contains an error, for 
example an open FOR-NEXT loop, an error message will appear and the 
program will not run. 


Control+Shift+Alternate 

By pressing this key combination a running program can be interrupted. 
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The line counter and the clock 


To the lower right of the menu list there is a counter that displays the number 
of the line with the cursor. A line number can also be entered in this space and 
the cursor will jump to that line. To accomplish this, the input field can be 
opened by clicking with the mouse pointer on this field, or by pressing CON- 
TROL-G. 


Only numbers will be accepted in this field. The editing options for this field 
are as follows: 


Cursor left Cursor moves one character to the left (as long as it is not 

to the far left already). 

Cursor right Cursor moves one character to the right (as long as it is 

not at the end of the input field). 

Backspace The same as cursor left 

ESC (Escape) Erases the Input field. 

RETURN/ENTER+ Accepts the entered number 


Above the line counter a clock displays the system time. The system clock 
may be reset by clicking on this block and entering the correct time. The edit¬ 
ing options are the same as those of the line counter with the exception of the 
escape key which will simply break out of setting the system time and the old 
time will be retained. 
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GFA-BASIC contains a small menu that can be invoked either by pressing the 

right mouse button or by pressing the right mouse button together with a 

character. The menu is toggled by clicking on the big Amiga-A symbol. 

Load (Amiga-L) like FI 

Save (Amiga-S) like Shift/FI 

New name (Amiga-N) toggles the confirmation for new variable names on 
and off. When on, a confirmation request follows the input of a 
new variable name to facilitate the correction of typing errors. 
This request is always present in direct mode because the new 
variables replace the old 

Run (Amiga-R) like Shift/FlO 

Taskpri 0 (Amiga-0) changes the task priority to 0, so that the background 
tasks are allocated processing time as well. 

Taskpri 1 (Amiga-1) changes the task priority to 1, so that the program is 
processed quicker in spite of other calculation intensive 
programs. For example, acceptable scrolling speed in this editor 
can be achieved while another GFA-BASIC program performs 
extensive calculations without waiting for keyboard input. 

Task priorities can further be modified (in an approximate range 
of -4 to +4) by using ~SetTaskPri(FindTask(0),n). 

Cleanup (Amiga-C) terminates all audible sounds, stops all Bobs and 

releases all sprites. 

NewCLI This menu item allows for initiation of a new CLI. 
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Variables and memory handling 
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Variable types 


The variable names in GFA-BASIC 3.0 begin with a letter (A to Z) followed 
by letters, numbers (0-9), dots (.), or underlines (_). 


GFA-BASIC 3.0 recognizes the following variable types: 


Name 

Postfix 

Memory requirement 

Boolean 

t 

1 byte (in arrays one bit) 

Byte 

1 

1 byte 

Word 

& 

2 bytes 

Integer 

% 

4 bytes 

Float 

# 

8 bytes 

String 

$ 

depends on string length 


Boolean variables can only have a value of 0 (false) or -1 (true). If a value is 
given that does not equal 0 then it will be given a value of -1. This variable 
type is seen with the postfix ! and occupies one byte of memory. In boolean ar¬ 
rays, an array element will only require one bit of memory. 


Example: 


b!=TRUE 

c!=xy 


The Byte variable type can have a value from 0 to 255. Larger values will be 
handled as overflow. The postfix for this type of variable is a vertical bar I. As 
the name implies this type of variable occupies only one byte of memory. 


Example: 

X|=128 

Word is a 2-byte integer type. The postfix for this type is &. This type of word 
variable can handle numbers from -32768 to 32767. 
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Example: 

x&=32767 

Integer variable is a 4-byte integer type. The % character is used as postfix. 
The numbers that can be used range from 2147483648 to 2147483647. 


Example: 

x%=2000000000 

Float is a floating decimal variable type requiring 8 bytes of memory. There is 
no postfix used with this type of variable. The available numbers are from 
2.225073858507E-308 to 3.595386269725E+308. 

Strings are marked with the postfix $. They can have a maximum length of 
32767 characters. String variables are managed with a descriptor. These 
descriptors have a length of 6 bytes. The first four bytes contain the address of 
the string, the last two bytes contain the length of the string. If the length of the 
string is uneven a fill byte will be placed behind the string. Following that is 
the address of the descriptor (back pointer). 

The address of all variable types can be obtained using the function VARPTR 
(or V:). With strings the address of the string will be given using VARPTR and 
with ARRPTR or * the address of the string descriptor will be returned. The 
address of individual array elements can be determined by using VARPTR/V 
(V: x%(5)) for example). With ARRPTR/* the address of the array descriptor 
can be determined (ARRPTR(x%())) for example). With VARPTR/V the ad¬ 
dress of the individual array elements can be determined, while ARRPTR 
determines the address of the array descriptor. 
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Arrays 


Arrays can be made up from any type of variable. Creation of such an array is 
accomplished by using the DIM command. The function DIM? determines 
how many elements an array contains. 

The management of arrays is accomplished by using descriptors. Such a 
descriptor is a six-byte long structure in which the first four bytes contain the 
address of the array. The next two bytes determine how many dimensions the 
array has. The array begins with four bytes for each dimension of the array. 
This is followed with the contents of the array elements. With string variables 
this is the descriptor of the character string. 

As an example the following case will be created by DIM a%(2,3): The ad¬ 
dress of the array descriptor can be found using *a%0- The number of dimen¬ 
sions can be found in the last two bytes of the descriptor. The equation 
INT{*a%0+4} will therefore return the value 2. The array begins with the 
number of subdivisions of the second dimension, where the null element is 
counted (That is, if OPTION BASE 0 is in effect). Behind this the number of 
divisions of the first dimension can be found. {(*a%0)) will return the value 
4 and ({*a%0+4} the value 3. 

The 12 array element will close with 4 bytes of memory each in the following 
order 

a%(0,0) a%(l,0) a%(2,0) a%(0,l) a%(l,l) a%(2,l) etc. 
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DEFxxx 


DEFBIT f$ 

DEFBYT f$ 

DEFINT f$ 

DEFWRD f$ 

DEFFLT f$ 

DEFSTR f$ 

f$: string constant 

The instruction DEFxxx serves to simplify the declaration of variables, xxx is 
a place holder for the abbreviation of the variable type. Their explanations and 
descriptions are in the following table: 


DEFxxx 

f$ 

Postfix 

all variables 

DEFBIT 

"b" 

i 

variables beginning with "b" will be 
declared boolean variables. 

DEFBYT 

"by" 

1 

variables beginning with "by" will be 
declare d 1-byte-integers. 

DEFWRD 

”w" 

& 

variables beginning with "w" will be 
declare d 2-Byte-Integers. 

DEFINT 

"i-k,m-p" 

% 

variables beginning with "i" through 
"k" and "m"through "p” will be 
declared 4-byte integers. 

DEFFLT 

"x-z” 

# 

variables beginning with "x" through "z" 
will be declared 8-byte floating point 
variables. 

DEFSTR 

"s,t” 

$ 

variables beginning with ”s" and "t" are 
declared suing variables. 

The editor 

will automatically replace DEFSNG or DEFDBL with DEFFLT. It 

is normally useful to make such global declarations at the beginning of a 


program. If one of these definitions is changed within the program it is only 
necessary to put the corresponding postfix on the variable. An explicit postfix 
has priority over a global definition of a variable. The declaration of a variable 
type is valid until another declaration is performed. The default variable type 
is DEFFLT. 
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LET 


LET x=y 

x: avar or svar 
y: aexp or sexp 

With the help of LET a variable can be assigned the value of an expression. 

The expression and the variable must both be either numeric or strings. Nor¬ 
mally the LET Instruction is unnecessary. This is a carryover from older ver¬ 
sions of BASIC and is included as a convenience to the programmer. GFA- 
BASIC automatically recognizes when a command word is being used as a 
variable name. 


Example: 

LET print=3 
PRINT print 
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CLEAR / CLR 


CLEAR 
CLR x [,y,—3 


x,y: svar or avar 

With CLEAR all variables and fields are erased. The command may not be ex¬ 
ecuted from within a FOR NEXT loop or a subroutine. This command is 
automatically executed at the start of every program and it is only useful when 
handling an error returned from a RESUME x operation. 

The command CLR erases all variables listed behind the command. Array 
variables cannot be erased using CLR. 


Example: 


x=2 
y=3 
CLEAR 
PRINT x.y 

x=2 
y=3 
CLR x 
PRINT x,y 

Displays on the screen the number 0 three times and the number 3 once. 
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ERASE 


ERASE Zl()[,z2(),...] 

x,y: array names 

ERASE erases a complete array. Any array erased using ERASE must 
dimensioned following execution of this command. Several arrays can 
erased using one ERASE command, ERASE xQ.yO for example. 


Example: 

DIM x(10) 

PRINT FRE(O) 

ERASE x() 

PRINT FRE(O) 

Two numbers are returned showing that the memory area reserved by the DIM 
command is released by the execution of the ERASE command. 
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DIM x(di,[d2,...]) [,y(di,[d2,...])] 
DIM?(x()) 


x,y: variable name (any variable type) 

d1,d2: iexp 

With the help of the DIM command, numerical and string fields can be 
created. The creation of such a field was described in the introduction to this 
section. 

From the practical point of view the number of dimensions in an array is limit¬ 
less. The number of elements of multi-dimensioned arrays is, however, limited 
in that the last dimension may have a maximum of 65535 elements. (Therefore 
DIM a%(100,10,10) for example, is allowed because the last element of the 
dimension (10) and the product of the number of array elements is less than 
65535) 

OPTION BASE determines if the array is to be a null array element or not. 
Only variables of the same type can exist within an array element. Access to 
an array element is done through the indices of the element The function 
DIM? determines how many elements an array has. 


Example: 

DIM x(10) 
x(4)=3 

PRINT x(LENfTesf)) 

PRINT DIM?(x()) 

DIM y%(2,3) 

PRINT DIM?(y%()) 

Create two arrays. Write a value to one of the arrays and then read it. Write the 
number of elements in both arrays on the screen (11 and 12). 
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OPTION BASE 


OPTION BASE 0 
OPTION BASE 1 

OPTION BASE determines if a null element will exist in an array. With OP¬ 
TION BASE 0 such a null element can be created, with OPTION BASE 1 this 
is not possible. In this case the array index will begin with 1. 

The contents of the field will not be changed by the OPTION BASE com¬ 
mand, however the position of the individual array elements will be changed 
by a value of 1. 

If no OPTION BASE command is given the array elements will begin with 0. 


Example: 

DIM x%(3) 

FOR i%=3 DOWNTO 0 
x%(i%)=i% 

PRINT i%,x%(i%) 

NEXT i% 

OPTION BASE 1 
FOR i%=3 DOWNTO 0 
PRINT i%,x%(i%) 

NEXT i% 

Display the index and the contents of the array x%0- The program ends with 
the error message "field index error", because x%0 has no null element after 
OPTION BASEL 
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INSERT / DELETE 


INSERT x(l)=y 
DELETE x(l) 

x: array name 
i: iexp 

y: aexp or sexp, depending on type of variable in the array 

With INSERT and DELETE one element can be inserted into or deleted from 
an array. INSERT inserts the value of the numeric expression y into the array x 
at the position i. With this, all elements of the array which have an index larger 
than i will be pushed up one position. When one element is at position i+3, 
after the INSERT command it will move to position i+4. The last element of 
the array will be deleted during the execution of this command. 

DELETE removes the nth element of the array x. All array elements which 
have an index larger then n are moved one position down. The last element of 
the array will become equal to 0 (with string fields the last element will be¬ 
come an empty space). Both of these commands can be used for the manage¬ 
ment of lists in which elements must be deleted or inserted. 


Example: 

DIM x%(5) 

FOR i%=1 TO 5 
x%(i%)=i% 
NEXT i% 

INSERT x%(3)=33 
FOR i%=0 TO 5 
PRINTx%(i%) 
NEXT i% 


Dim x%(5) 

FOR i%=1 TO 5 
x%(i%)=i% 

NEXT i% 
DELETE x%(3) 
FOR i%=0 TO 5 
PRINT x%(i%) 
NEXTi% 


The left example displays the numbers 0,1,2, 33, 3 and 4. The right example 
displays the numbers 0,1,2,4,5 and 0. 
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ARRAYFILL 


ARRAYFILL x(),y 

x: numerical variable type array name 
y: aexp 

The command ARRAYFILL sets all elements of the array x equal to the value 
of the numerical expression y. The value y may not exceed the area allowed 
within the array element That means for example an array made up of byte 
entries cannot be assigned integer sized values. 


Example: 

DIM x%(10) 

PRINT x%(4) 

ARRAYFILL x%().5+1 
PRINT x%(4) 

Displays the number 0, because after a DIM command all array elements are 
set to zero. After the array is filled the number 6 is displayed on the screen. If 
the number 70000 had been given instead of 5+1 in the ARRAYFILL com¬ 
mand the error message "Number not a Word" would appear. 
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ASC/CHR$ 


ASC(a$) 

CHR$(x) 

a$: sexp 
x: iexp 

ASC and CHR$ are complementary functions. The function ASC obtains the 
ASCII code of the first character in the string a$. If a$ is an empty string then 
a zero is returned. CHR$ returns the ASCII character that the code x has. Only 
the low byte is used (The formula used is x AND 255) 


Example: 

PRINT ASC(-TEST-) 

code|=ASC(CHR$(65)) !CHR$(65) returns 'A' 
PRINT code| 

Displays the numbers 84 and 65 on the screen. 
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BIN$ / OCT$ / HEX$ 


BIN$(x [,y]) 

OCTOBERS (x [,y]) 

HEX$(x [,y]) 

(x,y: iexp) 

BINS changes an integer number into a binary number. This means that after 
transformation the number will be in base 2 (binary) number system. With this 
command numbers are presented only with the digits 0 and 1. The parameter 
y gives the number of places to use (1 to 32). 

OCTS changes an integer number into the appropriate octal representation 
(base 8 number system). Here only numbers from 0 to 7 are represented. The 
optional parameter y gives the number of places to be used (0 to 11). 

HEXS changes an integer into the appropriate hexadecimal representation. 
With this base 16 number system the appropriate digits are 0 to 9 and A to F. 
The optional parameter y gives the number of hexadecimal places to be used. 


Example: 

x=32+15 

a$=OCT$( 16+7,4) 

PRINT HEX$(x),a$,BIN$(1+4+16+64,8) 

Displays 2F, 0027 and 01010101 on the screen. 
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STR$(x) 

STR$(x,y) 

STR$(x,y,z) 


STR$ 


x,y,z: aexp 

STR$ changes the value "x" into the corresponding character string. The 
second parameter ”y" determines the number of leading spaces to insert, i.e. 
how many characters of the resulting suing (counted from the end of the 
string) are to be used. 

STR$(x,n) corresponds to RIGHT$(SPACES(n)+STR$(x),n). 

Another variation of STR$ is possible with a third parameter z. With this 
parameter the number x starting at y with z characters is returned. 


Example: 

a=123.4567 
PRINT STR$(a,6,2) 

PRINT STR$(PI.5.3) 

PRINT STR$(PI,2,2) 

Displays the numbers 123.46,3.142 and 14 on the screen. 
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VAL 


VAL(a$) 

VAL?(a$) 

a$: sexp 

VAL() changes a character s^ing into a number. If VALO encounters a charac¬ 
ter that cannot be inteipre.ed as a number the analysis of the string will be 
stopped. The numbers at the beginning of the string will be returned from 
VAL. If no numbers are at the start of the string then zero will be returned. 

By using &H(hex), &X(bin), or &0(october), numbers in binary, octal or 
hexadecimal format will be assumed. 

You can determine how many characters a string contains by using VAL?0- 
VAL?() will return zero if there are no characters in the string. 


Example: 
a$=STR$(12345) 

PRINT VAL(a$),VAL("-.123 abc 123"),VAL?("3.00 dollars") 

Displays the numbers 12345, -.123 and 4 on the screen. 

PRINT VALC&HVAF") 

Displays the number 175. 

PRINT VAL("$AA") 

PRINT VAL(“%10101010") 

Both display the number 170 on the screen. 
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CINT / CFLOAT 


CINT(x) 

CFLOAT(y) 

x: aexp 
y: iexp 

The function CINT changes a floating point number "x" into a rounded integer 
value. CFLOAT, on the other hand, changes an integer value ”y" into a floating 
point number. These functions are not normally needed, and are only included 
to make the language description complete. They are only meaningful to the 
compiler. 


Example: 

a=1.2345 
a%=10000 
b%=CINT(a) 
b=CFLOAT(a%) 

PRINT b%,b 

Displays 1 and 10000 on the screen. 
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CVx / MKx 


cvi(a$) 

CVL(a$) 

MKI$(x) 

MKL$(x) 

MKS$(x) 

MKD$(x) 

a$: sexp 
x: aexp 

The Functions CVI, CVL, and CVF convert character strings into numbers. 

In contrast to VAL, STR$ creates no conversion into ASCII text, but rather to 
the internal presentation of the string. The CVX functions have the following 
applications: 

CVI Changes a 2 byte character string into a 16 bit integer. 

CVL Changes a 4 byte character string into a 32 bit integer. 

CVS Changes a 4 byte character string, containing an Amiga-BASIC com¬ 
patible number, into a floating point GFA-B ASIC integer. 
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CVx / MKx 


MKI$, MKL$, MKS$, MKF$, and MKD$ perform the reverse function of 
their CVx-function counterparts; the meaning of each can, therefore, be read 
from the previous table. An example of an application would be the reading of 
numeric data from other programming languages. 


Example: 

a$=MKL${1000) 

PRINT CVL(a$),LEN(a$) 
b$=MKI$( 100.1) 

PRINT CVI(b$).LEN(b$) 

Displays the numbers 1000 and 4 as well as the numbers 100 and 8 on the 
screen. 
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SWAP 


SWAP a,b 
SWAP e(),f() 

SWAP *c,d() 

a,b: avar or svar 

c: pointer to an array descriptor 

d,e,f: array name 

In its simplest variation the command SWAP serves to exchange the value of 
two variables of the same type (SWAP a,b). It can also be used to exchange the 
values of two arrays. The exchange of fields is very fast because only the ap¬ 
propriate descriptor is exchanged. In that way the dimension of both arrays are 
also exchanged. 

In the third variation, c contains the address of an array descriptor and dO is 
the name of the array, which is not dimensioned (see second example). A field 
with a name can be dimensioned and be called upon later with a different 
name; this is of interest when passing fields within subroutines (see second ex¬ 
ample). 

The command SWAP must not be mistaken for the function SWAP, which is 
explained in the section about bit operations. 

Example: 

X=1 

y=2 

PRINT x,y 
SWAP x,y 
PRINT x,y 

Displays the numbers 1 and 2 followed by 2 and 1 on the screen. 
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SWAP 


DIM x(3) 
change(*x()) 

PRINT x(2) 

PROCEDURE change(adr%) 

SWAP *adr%,a() 

ARRAYFILl a(),1 
SWAP *adr%,a{) 

RETURN 

The array x() is filled with the procedure change without the name x() appear¬ 
ing in the subroutine. The SWAP command gives the array a new name 
without forgetting the old one which can be utilized again with SWAP. 


The indirect array passing is recommended through the VAR parameter: 

DIM x(3) 

CHANGE (x()) 

PRINT x(2) 

PROCEDURE change (VAR a()) 

ARRAYFILL a(),1 
RETURN 
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QSORT / SSORT 


QSORTa(s) [,n] [,j%()] 

QSORT x$(s) OFFSET o WITH l() [,n [,j%()]] 

SSORT a(s) [,n] [,j%()] 

SSORT x$(s) OFFSET o WITH l() [,n [,j%()]] 

a(): any array, can also be a string array 

i(): integer array (|,& or %) 

j%(): 4-byte-integer array 

x$(): string array 
n,o: iexp 

s: +, - or no character 

With help from the commands SSORT and QSORT the elements of an array 
can be sorted by their size. With SSORT the shell sort is executed, with 
QSORT the quick sort is executed. 

A plus or minus symbol can be placed within the brackets, before the name of 
the array to be sorted. The minus sign implies that the element should be 
sorted in descending order. In this case the largest value of the array will be in 
the zero element of the array. The plus sign ensures that the array is sorted in 
ascending order; in the zero element the smallest value will then be found. If 
no symbol is given the default is then the plus sign. 

The parameter n means that only the first n elements of the array should be 
sorted, (in the case of OPTION BASE 0 this includes the elements 0 to n-1, 
otherwise 1 to n). An OFFSET can be set by using "o". This is the number of 
characters after the beginning of the string that are to be skipped during the 
sort. These characters are, therefore, ignored during the sort If a string is 
shorter than the number in "o" then an empty string is used as the sort criteria. 

Another integer array that is to be sorted with the first array can be given as 
the third parameter. Each exchange of elements of the first array will be fol¬ 
lowed by an exchange of elements in the second array. This can be used when 
one array is the sort key (for example zip codes) and many other arrays con¬ 
tain information that corresponds to that of the first array. The integer field that 
is sorted with the first array contains array indices "R" file indices, LOC 
values for SEEK etc. 
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QSORT/SSORT 


During the sorting of string arrays the sort criteria can be set in the form of an 
array with at least 256 elements. Without including WITH the normal ASCII 
table will be used as the sort criteria (see second example). 


Example: 

DIM x%(20) 

PRINT "Unsorted: *; 

FOR i%=0 TO 10 
x%(i%)=RAND(9)+1 
PRINT x%(i%);" *; 

NEXT i% 

PRINT 

QSORT x%(),11 
DIM index%{20) 

PRINT "Sort incrementing: ■; 

FOR i%=0 TO 10 
PRINT x%(i%);" 
index%(i%)=i% 

NEXT i% 

PRINT 

SSORT x%(-),11,index%() 

PRINT "Sort decrementing: *; 

FOR i%=0 TO 10 
PRINT x%(i%);" *; 

NEXT i% 

PRINT 

PRINT "Field sorted with: 

FOR i%=0 TO 10 
PRINT index%(i%);* 

NEXT i% 

Displays one unsorted and two sorted rows of random numbers. The fourth 
row contains the values of the array sorted with the fields. 
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QSORT / SSORT 


DIM b|(256) 

FOR i%=0 TO 255 
b|(i%)=ASC(UPPER$(CHR$(i%))) 

NEXT i% 

FOR i%=1 TO 7 
READ a$,b$ 
b|(ASC(a$))=ASC(b$) 

NEXT i% 

DATA A,b.C,d,a,B,c,D,3,2,5 > 4,6,5 
DIM n$(3) 

FOR i%=0 TO 3 
READ n$(i%) 

NEXT i% 

DATA Armbruster, Jones,Smith,Fenner-Broackway 
QSORT n$(),4 
FOR i%=0 TO 3 
PRINT n$(i%), 

NEXT i% 

PRINT 

QSORT n$() WITH b|(),4 
FOR i%=0 TO 3 
PRINT n$(i%) 

NEXT i% 

Sorts twice the string array n$0, once without WITH and once with WITH. 
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FALSE / TRUE / PI 


FALSE 

TRUE 

PI 

Both FALSE and TRUE contain the constant logical false and logical true. 
FALSE equals 0 and TRUE equals -1. PI contains the value of PI. 


Example: 

PRINT FALSE 
IF TRUE 
PRINT PI 
ENDIF 


Displays the numbers 0 and 3.14159265359 on the screen. 
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DATES / TIMES 


DATES 

TIMES 

time$, date$: sexp 

The function DATES determines the system date in the format: 
DD.MM.YYYY (Day.Month.Year), or MM/DD/YYYY (US format, see 
MODE). TIMES determines the system time in the format: HH:MM:SS 
(Hours:Minutes:Seconds). The date can also be set using DATES. The vari¬ 
ables DATES is set according to the previously explained formats. 

Example: 

PRINT DATES.TIMES 
DATE$="27.2.1988- 
PRINT DATES.TIMES 

Displays the current system date and time, resets the date variable with new 
data and displays the new date along with the time. 
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SETTIME 


SETTIME tlme$,date$ 

time$,date$: sexp 

With the command SETTIME the date and time can be reset To do this the 
strings TIMES and DATES must have the format just described under TIMES 
and DATES. For the years from 1978 to 2077 the century can be omitted. If 
the wrong format is used with the strings TIMES or DATES the actual value 
will not be changed. The time in TIMES must be entered in military time (24 
hour clock format), for example: 4:00pm is 1600. 


Example: 

PRINT DATES,TIMES 
SETTIME ’20:15:30',■27,2.1988" 

PRINT DATES,TIMES 

Prints the current system date and time to the screen, resets these variables and 
prints them out again. 
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TIMER 


TIMER 

The TIMER function will return the time since the system was turned on, in 
two hundredths of a second. The resolution of this clock is about one tenth of a 
second. 


Example: 

t%=TIMER 

FOR i%=1 to 25000 

NEXT i% 

PRINT (TIMER-t%)/200 

Displays the time, in seconds, that an empty loop requires for execution. 
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FRE 


FRE() 

FRE(x) 

x: aexp 

These functions calculate the free memory. The parameter x has no meaning 
except that FRE(x) carries out a garbage collection of unused memory areas in 
the upper memory range. FREE() returns the size of free memory area without 
the garbage collection. 


Example: 

free%=FRE(0) 
max%=free%/3/4 
DIM x%(max%) 

PRINT free%,max% 

Dimensions an array so that one third of the free memory area is used. A 4- 
byte integer element occupies 4 bytes per element, this is the reason for the 
division by 4. 
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TYPE 


TYPE(x) 

x: iexp 


A check can be made to ensure that a correct pointer to a variable is passed 
with the help of the function TYPE. An identification number for the type or 
the value -1 will be returned. The values returned, depending on the variable 
type will be: 


Float 

String 

Integer 

Boolean 

Float-Array 

String-Array 

Integer-Array 

Boolean Array 

Word 

Byte 

Word-Array 
Byte-Array 


-> 0 
-> 1 

-> 2 
-> 3 

-» 4 

5 

-» 6 
-> 7 

-4 8 

-> 9 

12 

-> 13 


Example: 

a$='test’ 
x%=4 
DIM y(3) 

PRINTTYPECaD.TYPECxyoJ.TYPECyO) 

Displays the numbers 1,2 and 4 on the screen. 
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DUMP 


DUMP [a$ [TO b$]] 

a$,b$: sexp 

Using the DUMP command variable contents as well as labels, procedures and 
functions can be listed during program execution. The string expression a$ can 
be given one of the following values: 


Example: 

DUMP 


Shows all variable values and the dimensions of all arrays. 

DUMP "a" 

Like above, but only variables that are arrays, beginning with "a" will be dis¬ 
played. 

DUMP ':b“ 


Lists all labels (marks) and gives the editor line number where the marks are 
defined. The variation (:b) lists only marks that begin with "b". 

DUMP •<§>■ 

Lists all procedures and functions; the line number where the function or pro¬ 
cedure can be found follows the procedure name. 


proc_name@ 100 
func_name FN 200 
func_name $ FN 300 


(Procedure) 

(Function with a numerical return) 
(Function with a string return) 
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DUMP 


Labels, procedures and functions that are no longer defined are shown without 
the line number. If this program listing is saved with SAVE A and then 
reloaded these undefined names are no longer there. 

To jump to the line behind a specific name use CONTROL+G within the 
editor. 

When strings are shown only up to 60 characters are displayed. If the string is 
longer than 60 characters the last character is an ”>" otherwise a double quote 
(") is shown. Command characters (that is, ASCII values) are represented by a 


The output described above can also be sent to a data file. For this, b$ must be 
given a file name. 

The default file extension of this file will be .DMP. 
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VARPTR/ARRPTR 


VARPTR(x) 

V:x 

ARRPTR(y) 

*y 

x: name of a variable of any type 
y: array name 

With ARRPTR(y) or *y the address of a variable y, or in case of strings or ar¬ 
rays the addresses of their descriptors can be determined. 

VARPTR(x) or V:x returns the address of the string itself, (when used in con¬ 
junction with a string) or the address of an array element (when used in con¬ 
junction with an array). 

For scale variables (variables that are neither strings nor arrays) VARPTR, V:, 
ARRPTR and * have the same meaning. 


Example: 

DIM x%(10) 

A$= -TEST- 

PRINT ARRPTR(x%()),VARPTR(x%(0)),V:X%( 1) 

PRINT ARRPTR(a$),*a$,VARPTR{a$) 

Returns on the first line the address of the array descriptor as well as the ad¬ 
dress of both the first array elements of x%0- On the second line the address 
of the string descriptor of a$ is displayed twice and the address of the first 
bytes of the character string is displayed once. 
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* 


*x 


x: svar or an array name followed by () 

The multiplication symbol can also be used as the pointer symbol. 

In this case *x returns the address where in memory the variable x can be 
found. With string variables *x$ returns the address of the string descriptor 
(ARRPTR(x$)). The expression *x is, therefore, identical to ARRPTR(x). This 
applies to arrays also. 

This variation of the pointer application has a special use for the indirect pass¬ 
ing of arrays to subroutines. The instruction VAR is better suited for this pur¬ 
pose. 


Example: 

' indirect passing of an array 

DIM a(3) 

change(*a()) 

PRINT a(2) 

PROCEDURE change(ptr%) 

SWAP *ptr%,x() 

ARRAYFILL x(),1 
SWAP *ptr%,x() 

RETURN 

The contents of the array a() is changed without its name being mentioned in 
the Procedure. The number 1 is displayed on the screen (see also SWAP). 


The same example with VAR: 

DIM a(3) 
change(a()) 

PRINT a(2) 

PROCEDURE change(VAR x()) 
ARRAYFILL x(),1 
RETURN 
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POKE 


POKE x,y 
DPOKE x,y 
LPOKE; x,y 

x,y: iexp 

With the help of the POKE command and its variations, values can be written 
directly to memory. The individual command variations are: 

POKE x.y writes the value y as one byte at the address x 
DPOKE x.y writes y as a two-byte value at the address x 
LPOKE x,y writes y as a four-byte value at the address x 

Care must be taken to ensure that only even addresses are used with LPOKE 
and DPOKE. 


Example: 

DATA 45,20,30,72.84,213,55,153,90,12,145,43 

IF adr%=MALLOC(24,2) ! reserves 24 BYTES of memory 

FOR i&=0 to 23 
READ b& 

POKE adr%+i&,b& 

NEXT i& 

ENDIF 

Reserves memory, reads the byte values from the DATA line and writes these 
to memory. 
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PEEK 


PEEK(x) 

DPEEK(x) 

LPEEK(x) 

The contents of a position in memory can be read directly with the PEEK 
function: 

PEEK(x) reads one byte from address x 
DPEEK(x) reads two bytes starting at address x 
LPEEK(x) reads four bytes starting at address x 

As with the POKE command, care must be taken to ensure that only even ad¬ 
dresses are specified. 

Example: 

FOR i&=0 TO 23 
PRINT PEEK(adr%+i&) 

NEXT i& 

Displays the value returned by PEEK on the screen. 


2-36 


GFA-BASIC 3.0 Amiga 




{X} 


BYTE{x} 

CARD{X} 

INT{X}, WORD{x} 

LONG{x}, {x} 

FLOAT{x} 

SINGLE{x} 

DOUBLE(x) 

CHAR{x} 

x: iexp 

With the help of these commands, certain variable types can be read or written 
starting at an address. As a function (for example y=BYTE{x}) it reads from 
an address x. As a command (for example BYTE{x}=y) it writes the value y 
to the address x. 

Care must be taken to ensure that only even addresses are used with INT{}, 
CARD {}, WORD (}, LONG {},{}, FLOAT {}, SINGLE [} and DOUBLE {}. 


Type 

BYTE{x} 

CARD{x) 

INT{x},WORD(x} 

LONG(x},{x} 

FLOATfx} 

SINGLE (x) 
DOUBLE (x) 

CHAR{x} 


Meaning 
one byte 

one 2-byte integer without leading character 
one 2-byte integer with leading character 
one 4-byte integer value 

one 8-byte floating point variable in GFA-BASIC 3.0 
Format 

one 4-byte floating point variable in IEEE Single Format 
one 8-byte floating point variable in IEEE Double For¬ 
mat 

one string ending with a null byte. Extremely important 
for communication with C routines 
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{X} 


With x%=LONG{adr%) the variable x% will be given the value of the long 
word contained at the address adr%, and with LONG{adr%)=x% the address 
adr% will be given the value of the variable x%. 

With the SINGLE and DOUBLE instructions it is possible to read and write a 
foreign number format For example, many C-Compilers use the IEEE Double 
Format. In order to change a GFA-BASIC 8-byte floating point value into a 
SINGLE or DOUBLE format and to control hexadecimal outputs the follow¬ 
ing can be written: 

a$=SPACE$(4) 

SINGLE{V:a$}=1.2345 
PRINT HEX$(CVL(a$),8) 

or 

a$=SPACE$(8) 

DOUBLE{V:a$}=1.2345 
PRINT HEX$({V:a$},8) 

PRINTHEX$({V:a$+4),8) 

Some of the above named functions are similar to the PEEK function, 
LONG(x) (or {x}) are similar to LPEEK(x). 


Example: 

a$=CHAR{{SCREEN(1)+22}} 
Reads the title of a screen. 
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ABSOLUTE 


ABSOLUTE x,y 

x: a variable of any type 
y: iexp 

With the command ABSOLUTE the address (ARRPTR/*) of a variable will be 
changed. The variable will then be sent to the given address. It will also ac¬ 
quire the value of the new address. The value in y must be an even value, as 
long as x does not contain a boolean, byte or string variable. 

This command should only be used by programmers with some knowledge of 
the operating system. The assignment of an address can not simply be under¬ 
taken without having an effect on the entire Amiga system. For example, sys¬ 
tem addresses can be given variable names using ABSOLUTE. 


Example: 


x=13 

y=7 

ABSOLUTE y,*x 
PRINT x,y,*x,*y 

Here the variable y is sent to the address x so that in the end both variables 
will have the same value (7) and the same address. 
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VOID 


VOID fx 
-II 

fx: aexp 
fi: iexp 

In programming languages, commands and functions are normally differen¬ 
tiated. Commands guide the execution of some type of operation. 

Functions find a value which is then returned. This value can then be used as a 
part of an expression, output with PRINT or compared to a variable, etc. 

In many cases the programmer is not interested in what is returned from a 
function, but in the results which are produced by the function. For example 
the function WAIT will return a signal bit If the program should simply wait 
the signal bit has no meaning. In such a case GFA-BASIC can be used to ex¬ 
ecute the function, but then forget the value that is returned. In contrast to 
VOID the tilde (~) calculates an integer expression and then forgets it. With 
VOID, for example, an overflow may execute a change into a floating point 
expression when using WAIT. The compiler is then aware of the overflow. 


Example: 

VOID WAIT 
or 

-WAIT 

Waits for a report without the (here overflowing) assignment of the variable 
dummy=WAITO- With tilde the interpreter does not need to convert the result 
of WAITO into a floating point decimal value. 
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MALLOC / MFREE 


MALLOC(x,art) 

MFREE(y,a) 

x,y,art,a: iexp 

The function MALLOC serves to reserve (allocate) blocks of memory. 

If x is a positive number then x bytes will be allocated and the address will be 
returned. If an error is encountered, a zero or some negative value is returned. 

What type of memory is to be reserved is determined by the type of expression 
employed. The following types can be used. 

2(&H2) MEMF CHIP 

Use chip memory. This is memory that can also be used by the graphic chips. 
1(&H1) MEMFPUBUC 

This type should be chosen when the compatibility of the program with future 
operating systems is to be ensured. 

4(&H4) MEMF FAST 

Memory area outside of the graphic chip range will be used. 

65536(&H10000) MEMF CLEAR 

MEMF_CLEAR can be combined with all other types. Before MALLOC 
returns the memory address the memory area is filled with zeros. 

The memory area created with Malloc is always outside of the memory area 
used by the interpreter for variables. 
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MALLOC / MFREE 


Allocated memory areas should be returned to the system before the end of the 
program. This is not automatically done when exiting the interpreter. 

MFREE (FrecMem) frees the memory area allocated by MALLOC. The start 
address is assigned to the variable y. This is the address that was returned by 
MALLOC. a is the number of bytes to be returned to the system. 


Example: 

adr%=MALLOC(60000,&H 10000) 

PRINT adr% 

IF adr%0 

return%=MFREE(adr%.60000) 

ENDIF 

Reserves a memory area 60000 bytes in size, displays its address on the screen 
and returns the area to the system (as is required at the end of every program). 
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BMOVE 


BMOVE; src,dst,cnt 

src.dst.cnt: iexp 

With the help of the command BMOVE memory blocks can be copied. The 
expression src must contain the address of the beginning of the block. In dst 
the address in which the memory block is to be copied to must be found. And 
cnt contains the number of bytes to copy. 

The command is executed noticeably faster with even parameters than it is 
with odd parameters. It can also be executed when the original block and the 
copy block overlap. 


Example: 

OPENS 1,0,0.320.200,1,128 

bm%=LPEEK(SCREEN(1)+88) 

bp%=LPEEK(bm%+16) 

DIM a%(1000) 

BMOVE bp%,*a%(),2000 

Copies the first 1000 bytes from the screen bit plane into the array a%. 
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RESERVE 


RESERVE [n] 

n: iexp 

The si/e that GFA-BASIC should use can be set with the help of the 
RESERVE command. When GFA-BASIC is started an area of 64K bytes is 
reserved, "n" is assigned the value returned by the command FRE(0). 

All variables are erased when this command is executed. RESERVE, there¬ 
fore, should only be executed at the beginning of a program. 


Example: 

RESERVE 1024 
PRINT FRE(O) 

Reserves 1024 bytes for the program and displays the program memory size. 
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3 - Operators 



Operator hierarchy 


When various operators are found in an expression they are processed in a 
specific order. This order is dependent on its place in the operator hierarchy. 
The operators found at the top of this hierarchy are processed first. 


The hierarchy is as follows: 

( ) 

+ 

= <>=><= o 
+ - 
A 

V 

DIV MOD 
+ - 

= = <<=>=> o 
AND OR XOR IMP EQV 
NOT 


Parentheses 
String addition 
String comparisons 
Prefixes 
Power sign 

Multiplication, Division 

Whole number division and modulo 

Addition, Subtraction 

Comparison operations 

Logical operations 

Negation 


It is possible to process operators that are low in the hierarchy first by placing 
them within Parentheses. In the order of operators the rule "points before line 
calculations" is also recognized. 


Example: 

PRINT 2+4*3 
PRINT (2+4)*3 
PRINT 2+(4*3) 

PRINT 3*2*2 

The numbers 14,18,14 and 12 are displayed on the screen. 


3-2 


GFA-BASIC 3.0 Amiga 




Logical operators 


The logical operators AND, OR, XOR, NOT, IMP and EQV work on bit level 
for 32-bit integer values. 

Logical operators combine two logical expressions and return a logical value 
(true or false). One exception is the operator NOT, which negates the logical 
values of the expressions that are located behind it 

The numerical value for logical false is 0. Every other number value will be 
interpreted as true. The variable TRUE has the value -1. All logical operators 
can also be used with numerical expressions. In this case the logical operations 
are carried out bit by bit 

How logical operators work can best be described using truth tables. In these 
tables the logical value of the combined expression (Operand) is found in the 
first column and the resulting logical value is found in the last column. 
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3-3 




NOT 


NOT x 

x: iexp 

The operator NOT (Negation) negates the logical expressions which are be¬ 
hind it. It is the only logical operation with only one argument. 


X 

NOT x 

t 

f 

f 

t 


Example: 

PRINT NOT FALSE 
PRINT NOT TRUE 
PRINT NOT 0 

The numbers -1,0, and -1 are displayed on the screen. 


x=1 

PRINT BIN$(x,2) 

PRINT BIN$(NOT x,2) 

01 and 10 are displayed on the screen. 


x%=17 

PRINT BIN${x%,8),x% 

PRINT BIN$(NOT x%,8),NOT x% 

Output 
00010001 17 
11101110 -18 
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x ANDy 

x.y: iexp 


AND 


The logical operator AND (conjunction) returns -1 (TRUE) if two logical ex¬ 
pressions x and y are true. The value TRUE (logical true, -1) will be given 
only if both are true. If one or the other are logically false then AND will 
return a logical false (0). 


X 

y 

x AND y 

t 

t 

t 

t 

f 

f 

f 

t 

f 

f 

f 

f 


Example: 

PRINT TRUE AND -1 
PRINT FALSE AND TRUE 

The numbers -1 and 0 are displayed on the screen. 


x=3 

y=10 

PRINT BIN$(x,4) 

PRINT BIN$(y,4) 

PRINT BIN$(x AND y,4).x AND y 

Output 

0011 

1010 

0010 

2 


Operators 


3-5 





OR 


xORy 

x,y: iexp 

OR (disjunction) checks that at least one of two logical expressions is true. In 
this case, logical true is returned. Only when x and y are both false will x OR y 
return logical false. In contrast to XOR, in which false will be returned only 
when x and y are both logical true. 

Or means that one or both of the arguments was true. 


X 

y 

x OR y 

t 

t 

t 

t 

f 

t 

f 

t 

t 

f 

f 

f 


Example: 

PRINT TRUE OR -1 
PRINT FALSE OR TRUE 
PRINT 0 OR FALSE 

The numbers -1, -1 and 0 are displayed on the screen. 


x=3 

y=10 

PRINT BIN$(x,4) 

PRINT BIN$(y,4) 

PRINT BIN$(x OR y,4),x OR y 

Output 

0011 

1010 

1011 and the number 11 are displayed on the screen. 
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XOR 


xXORy 

x,y: iexp 

This operator checks if either of two logical expressions x and y is logical true. 
In this case x XOR y will return logical true. If both x and y arc logical true 
then XOR will return logical false. 

In contrast to OR, TRUE OR TRUE is true while TRUE XOR TRUE is false 
(XOR = exclusive disjunction). 

XOR returns true when (and only when) only one of the corresponding bits in 
the arguments is set. 


X 

y 

x XOR y 

t 

t 

f 

t 

f 

t 

f 

t 

t 

f 

f 

f 


Example: 

PRINT FALSE XOR -1 
PRINT -1 XOR 1 
PRINT 0 XOR FALSE 

The numbers -1,0 and 0 are displayed on the screen. 


x=3 

y=10 

PRINT BIN$(x,4) 

PRINT BIN$(y,4) 

PRINT BIN$(x XOR y,4),x XOR y 
Output: 

0011 1010 1001 9 
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IMP 


x IMP y 

x,y: iexp 

The operator IMP (implication) corresponds to a logical following. Such a 
logical following can only be false when something false follows a true ex¬ 
pression. Therefore x IMP y can only be false when x is true and y is false. 


In contrast to AND, OR, XOR and EQV the order of the arguments is impor¬ 
tant 


X 

y 

x IMP y 

t 

t 

t 

t 

f 

f 

f 

t 

t 

f 

f 

t 


Example: 

PRINT TRUE IMP -1 
PRINT 0 IMP FALSE 
PRINT TRUE IMP 0 

The numbers -1, -1 and 0 are displayed on the screen. 


x=3 

y=10 

PRINT BIN$(x,4) 

PRINT BIN$(y,4) 

PRINT BIN$(x IMP y,4) 

Output 

0011 

1010 

1110 
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EQV 


xEQVy 

x,y: iexp 

The operator EQV (equivalency) returns logical true when the expressions x 
and y both have the same logical value. 

EQV works at the bit level and sets the bits that are the same in both argu¬ 
ments. This is the opposite of XOR, so (x EQV y) is the same as (NOT x 
XOR y). 


X 

y 

xEQVy 

t 

t 

t 

t 

f 

f 

f 

t 

f 

f 

f 

t 


Example: 

PRINT TRUE EQV FALSE 
PRINT FALSE EQV FALSE 

The numbers 0 and -1 are displayed on the screen. 


x=3 

y=10 

PRINT BIN$(x,4) 

PRINT BIN$(y,4) 

PRINT BIN$(x EQV y,4) 

Output: 

0011 

1010 

0110 
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X/- 


x + y 
x-y 
a$ + b$ 

x,y: iexp 

a$,b$: sexp 

Any arithmetic expression can be added or subtracted with + and Plus and 
minus can also be used as prefixes. Please pay attention to the various operator 
hierarchies (see the beginning of this chapter). 

Character strings can also be combined using the + operator. The result is a 
character string that contains both a$ and b$. A minus combination is not pos¬ 
sible for character strings. 


Example: 

a$="GFA-’ 

PRINT a$VBASIC- 

The text "GFA-BASIC" is displayed on the screen. 
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x=y 


x,y: exp 

The operator = compares if two numerical or character string expressions are 
equal. When both are equal then logical true will be returned, otherwise logi¬ 
cal false will be returned. 


Example: 


x=6 

IF 2=x/3 
PRINT ’Ok' 

ENDIF 
PRINT 2=x/3 

"Ok" and -1 are displayed on the screen. 
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x=y 


x: var 
y: exp 

The = (equal sign) can serve not only as a comparison operator, but also as an 
assignment operator. Here the value to the right of the equal sign is assigned to 
the variable on the left. Numerical expressions can only be assigned numerical 
variables, character string expressions can only be assigned string expressions. 

To assign a value to a variable the command LET var=exp (see LET) can also 
be used. 


Example: 

x=LEN('TEST’)+3 

a$='GF-+CHR$(65) 

PRINT x,a$ 

The number 7 and "GFA" are displayed on the screen. 
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x==y 


x,y: aexp 

The operator == compares two numerical expressions for approximate 
equality. With this comparison 8.5 decimal places (28 Bit of the mantissa of 
the floating point) are used. The application of == is useful when floating 
decimal numbers are used which could be affected by the inaccuracy of round¬ 
ing. 


Example: 

PRINT 1.0000000001=1 
PRINT 1.0000000001 ==1 

The numbers 0 and -1 are displayed on the screen. 

a=SINQ(77) 

b=SIN(RAD(77)) 

PRINT a=b 
PRINT a==b 

The values 0 (logical false) and -1 (logical true) are displayed on the screen. 
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<><=>= 


x<y 
x>y 
x <= y 
x >= y 

x,y: exp 

These operators serve to compare numerical and string expressions. In the case 
of numerical expressions the results of the expressions are compared. 

With string expressions the comparison is done according to the ASCII code of 
the character. The string "ABC" is compared using the values 65, 66, and 67. 
With the comparison "ABC'VAAA", first both of the start characters, with 
the ASCII code 65, are compared. Now the next character from each string is 
compared. Because B (ASCII code 66) has a higher code than A, B is con¬ 
sidered "larger". The comparison of the strings is ended at this position and the 
result given is logical true, "ABC" is therefore larger than "AAA". 

This string comparison will end when either of the strings end before an une¬ 
qual character is found. One example would be: "AA">"A". This result is logi¬ 
cal true, because no character exists which is of a "smaller" value. Even 
"A"+CHR$(0)>"A" is logical true. Now to the individual operators: 

x > y is true when x is larger than y 
x < y is true when x is smaller than y 
x >= y is true when x is larger than y 
x <= y is true when x is smaller than y 


x<=y and x=<y as well as x>=y and x=>y have the same value. And xxy is 
changed into xoy. 
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Example: 

PRINT ’AAAVaaa* 

PRINT -1<=4-5 

The numbers 0 and -1 are displayed on the screen. 


Operators 


< > 


x<> y 

x.y: exp 

This operator determines if two numerical or string expressions are unequal. 
When this is the case then the expression xoy is logically true. If x and y are 
equal then xoy is logical false. It does not matter how this is written, xoy is 
the same as xxy. 

Example: 

PRINT "Test’o'test" 

PRINT -1<>4-5 

The numbers -1 and 0 are displayed on the screen. 
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4 - Numeric functions 
and strings 



ADD / SUB / MUL / DIV 


ADO x,y 
SUB x,y 
MUL x,y 
DIV x,y 

x: avar 
y: aexp 

The command ADD increases the value of the variable x by the value y, while 
SUB decreases the value of the variable x by the value y. MUL multiplies x by 
y and returns the result in x. DIV divides the variable x into y and returns the 
result in x. The variable must contain a numeric value with each of these com¬ 
mands. These commands also function with floating decimal point variables, 
but are noticeably faster with integer variables. It is important to realize that 
no overflow check is executed with ADD, SUB, MUL or DIV when integer 
variables (%,&,!) are used. 


The command MUL a%,3.5 is executed like MUL a%,3 because with integer 
variables integer multiplication as well as division is used. 


ADD x,y 
SUB x.y 
MULx.y 
DIV x.y 


corresponds to x=x+y 
corresponds to x=x-y 
corresponds to x=x*y 
corresponds to x=x/y 


Example: 

x%=1 

y%=2 

z%=3 

ADD x%,y% !now x equals 3 

SUB z%,(x%-1)/2 !the numerical expression (x%-1)/2 'returns 1 

PRINT x%,y% 


The numbers 3 and 2 appear on the screen. 
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ADD / SUB / MUL /DIV / MOD 


ADD(x.y) 

SUB(x,y) 

MUL(x.y) 

DIV(x,y) 

MOD(x.y) 

x,y: iexp 

These functions can be used with the following numeric operators: 


ADD(x,y) 

SUB(x,y) 

MUL(x.y) 

DIV(x,y) 

MOD(x,y) 


corresponds to x+y 
corresponds to x-y 
corresponds to x*y 
corresponds to x/y (x DIV y) 
corresponds to x MOD y 


Because the functions described above work with integer arithmetic any 
decimal places are ignored. 


x%=5 
y%=4 
ADD y%,3 
z%=SUB(x%,3) 

Returns for x% the value 5, for y% the value 7 and for z% the value 2. 


The functions ADD, SUB, MUL, DIV and MOD can be grouped together in 
any manner. This arithmetic grouping is called polish notation. 
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ADD / SUB / MUL /DIV / MOD 


Example: 

OEFINT “a-z* 
x=4 

y=ADD(x,x) !y becomes equal to 8 
z=SUB(x,2) 

PRINT y,z,ADD(x,2*y) 

The numbers 8,2 and 20 are displayed on the screen. 

DEFINT'a-z' 

x=2 

y=MUL(x,3) !y becomes equal to 6 

PRINT y,DIV(8,x),MOD(11,4) !MOD(11,4) is equal to 3 

The numbers 6,4 and 3 are displayed on the screen. 

DEFINT":a-z" 

x=5 

y=ADD(SUB(x.2),MUL(3,4)) 

PRINT y.DIV(8,MOD(14,4)) 

The numbers 15 and 4 are displayed on the screen. 
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SIN / COS / TAN 


SIN(x) 

COS(x) 

TAN(x) 

ASIN(x) 

ACOS(x) 

ATN(x) 

x,degree: aexp 

These are the trigonometric functions. The numerical expression is interpreted 
in radians. The functions calculate: 

SIN 
COS 
TAN 
ASIN 
ACOS 
ATN 


Example: 
x=90 

y=COS(x*PI/180) 

Z=270*PI/180 
PRINT y,SIN(z),TAN(45),ATN(1/2) 

The numbers 1,-1, 2.84217094304E-14 and 0.4636476090008 are displayed 
on the screen. 


Sine 
Cosine 
Tangent 
Arc sine 
Arc cosine 
Arc tangent 
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SINQ / COSQ 


SlNQ(degree) 

COSQ(degree) 

degree: aexp 

The functions SINQ and COSQ return the interpolated sine and cosine respec¬ 
tively. GFA-BASIC uses an internal table in degree increments for this. The 
corresponding values are linearly interpolated in 1/16 degree steps. 

This exactness suffices for graphic representations on the screen and has no ef¬ 
fect on values calculated with SIN and COS, but is much faster (as much as 10 
times as fast). In contrast to SIN and COS, SINQ and COSQ expect their 
parameters in degrees. 

SINQ(degree) corresponds to SIN(RAD(degree)) 

COSQ(degree) corresponds to COS(RAD(degree)) 


Example: 

alpha%=30 
PRINT SINQ(alpha%) 

displays 0.5 on the screen. 

radio s=PI/2 

slow=SIN(radius) 

fast=SINQ(DEG(radius)) 

PRINT slow fast 

Calculates approximately the same value. Pay attention to the conversion into 
degrees when using SINQ. 
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DEG / RAD 


DEG(x) 

RAD(degree) 

x,degree: aexp 

In order to convert an angle from radians into degrees the function DEGO and 
the opposite function RAD() are used. DEG(x) corresponds to (x* 180/PI). 
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SQR 


SQR(x) 

x: aexp 

Returns the square of the numeric expression x. When the expression x is 
smaller then zero an error is returned. 

Example: 

X=9 

y=SQR(x) 

PRINT y,SQR(4*4) 

The numbers 3 and 4 are displayed on the screen. 

PRINT SQR(SQR(16)) 

PRINT SQR(-2) 

The number 2 and then an error message are displayed on the screen. 
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EXP / LOG 


EXP(x) 

LOG(x) 

LOGlO(x) 

x: aexp 

EXP calculates the xth power to the base of the number (e=2.1782818284...) 
and LOG is the reverse function, returning the logarithm of x base e (natural 
logarithm). The opposite of this is the LOG 10 function which returns the 
logarithm of x in base 10. 


Example: 


x=2 

y=EXP(2) 

PRINT y,LOG10(2*5),LOG(x) 

The numbers 7.389056098931, 1 and 0.6931471805599 are displayed on the 
screen. 
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DEC / INC 


DEC I 
INCi 

i: avar 

The command DEC and INC serve to change the value by one. DEC decre¬ 
ments the numeric variable i by one, while INC increments the numeric vari¬ 
able i by one. 

These commands work with floating point variables, but are considerably 
faster with integer variables. It is important to know that INC and DEC per¬ 
form no overflow check with integer variables (%,&,!). 

DEC x corresponds tox=x-l 

INC x corresponds tox=x+1 

Example: 

x%=4 
y%=7 
DEC x% 

INC y% 

PRINT x%,y% 

The numbers 3 and 8 are displayed on the screen. 

a|=255 
INC a| 

INC a| 

PRINT a| 

Returns 1 !, because there is no error checking. 
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PRED/SUCC 


PRED(i) 

SUCC(I) 

i: iexp 

PRED returns the next smaller number and SUCC returns the next larger num¬ 
ber. PRED and SUCC return respectively the predecessor and successor of a 
numeric expression. Both functions work with integer arithmetic, decimal 
values are therefore ignored. 

Both these functions are available for string expressions (See the section about 
string management). 


Example: 

e%=6 

j%=PRED(e%) 

PRINT j%,SUCC(2),PRED(3*e%) 

The numbers 5,3 and 17 are displayed on the screen. 
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ABS/SGN 


ABS(x) 

SGN(x) 

x: aexp 

The function ABS returns the absolute value of a numeric expression. This 
results in the following return values: 

If x is then ABS(x) is: 
negative -x 

equals 0 0 

positive x 

What prefix a numeric expression has can be found using the function SGN. 
From this it follows that: 

If x is Then SGN(x) is: 

negative -1 

equals 0 0 

positive 1 

Example: 

x=-2 

y=ABS(x) 

PRINT SGN(x),ABS(5-3),SGN(ABS(x*3)) !ABS(x*3) equals 6 
The numbers -1,2 and 1 are displayed on the screen. 
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INT / TRUNC / FIX / FRAC 


INT(x) 

TRUNC(x) 

FIX(x) 

FRAC(x) 

x: aexp 

These functions return the number of places in front of and behind the decimal 
for numeric expressions. INT, TRUNC (and the function TRUNC which is 
identical to FIX) return a whole number. The function TRUNC cuts the num¬ 
ber off after x decimal places. INT returns the largest whole number which is 
smaller or equal to x. The difference between TRUNC (FIX) and INT is not 
noticeable with positive x values. A difference is noticed with negative num¬ 
bers that have a fractional value. TRUNC will return the value -1 when x 
equals -1.2 by removing the fractional value. INT searches for the next whole 
number smaller than -1.2 and returns -2 as the result. 

FRAC returns the fractional value of x, removing the whole number value. 
The value returned from FRAC maintains the same prefix as x. FRAC is com¬ 
plimentary to TRUNC and not to INT. The following is true: 

x = TRUNC(x) + FRAC(x) 

If TRUNC is replaced with INT then the comparison will no longer be true for 
negative values (y equals -1.2 for example). 


Example: 

x=-1.4 

y=TRUNC(1.3) 

PRINT y,INT(x),FIX(3*x),FRAC(x-3) 

The numbers 1, -2, -4 and -0.4 are displayed on the screen. 
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ROUND 


ROUND(x,[n]) 

x: aexp 
n: iexp 

The function ROUND(x) returns a rounded value. The variation ROUND(xn) 
rounds the expression "x" to ”n” decimal places. If "n" equals zero then 
ROUND(x) will be rounded to whole numbers. If n is negative then the num¬ 
ber is rounded before the decimal. In this case ROUND(155,-l) will return the 
number 160. 


Example: 

y=ROUND(-1.2) 

PRINT y,ROUND(1.7) 

Displays -1 and 2 on the screen. 

FOR i%=-5 TO 5 
PRINT i%,ROUND(pi*100,i%) 

NEXT i% 

Displays the running variable and the appropriate formatted expression on the 
screen. The number pi multiplied by 100 and rounded to i% places. If i% is 
negative the number will be rounded before the decimal place. 
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ODD/EVEN 


ODD(x) 

EVEN(x) 


x: aexp 

Both of these functions check whether the numerical expression x is even or 
odd. ODD returns the value -1 (TRUE) when x is uneven and 0 (FALSE) 
when x is even. EVEN gives -1 when x is even and 0 when x is uneven. 0 is 
handled as an even number. 


If x is: Then ODD(x) is: EVEN(x) is: 


even 0 (FALSE) -1 (TRUE) 

uneven -1 (TRUE) 0 (FALSE) 

equals 0 0 (FALSE) -1 (TRUE) 


Example: 

x=2 

PRINT ODD(x),EVEN(-2),ODD(3*5), EVEN(-3*x) 

The numbers 0, -1, -1 and 0 are displayed on the screen. 
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MIN / MAX 


MIN(x [,y,z,...]) 

MIN(x$ [,y$,z$,...]) 

MAX(x [,y,z,...]) 

Max(x$ [,y$,z$,...]) 

x,y,z: aexp 

x$,y$,z$: sexp 

The function MAX returns the largest numeric expression that can be found in 
the parameter list x,y,z.The opposite of this is MIN which returns the smal¬ 

lest expression. Besides this, the functions MIN and MAX can also be used 
with string expressions. 


Example: 

=3 

y=MAX(3,5,5-4) 

PRINT MIN(x,y),MAX(-1 ,x*2) 

The numbers 3 and 6 are displayed on the screen. 
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RND/RANDOM 


RND [(x)] 

RANDOM(x) 

RAND(y) 

RANDOMIZE y 

x: aexp 
y: iexp 

This group of commands serves to produce random numbers. RND creates a 
random number between 0 and 1 (including 0, excluding 1). The optional 
parameter x has no meaning. 

RANDOM returns a random integer number between 0 and x (including 0, ex¬ 
cluding x). The numerical expression must not be a whole number when all 
numbers should not have the same possibility of being returned. 

RAND returns a random 16-Bit integer number from 0 to y-1. 

The command RANDOMIZE seeds the random number generator with the 
value y. In this way, the same chain of numbers will be returned each time the 
random number generator is seeded with the same y value. Run the random 
number generator to set each program with a random beginning number. 
Without RANDOMIZE different random numbers will be returned with RND, 
RANDOM or RAND each time the program is run. 

RANDOMIZE without parameters or RANDOMIZE 0 can be used to initial¬ 
ize the random number generator. 
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RND/RANDOM 


Example: 

x=RND 

PRINT x,RND(2) 

Two random numbers between 0 and 1 are displayed on the monitor. 

x=RANDOM(2) 

y=RAND(4) 

PRINT x,y,RAND(x),RANDOM(3*x) 

Four random numbers are displayed on the screen. 

RANDOMIZE 3 
x=RND 

RANDOMIZE 3 
PRINT x.RND 

The same random number are displayed on the screen twice. 
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BCLR / BSET / BCHG / BTST 


BCLR(x,y) 

BSET(x.y) 

BCHG(x.y) 

BTST(x,y) 

x,y: iexp 

These commands allow the erasing, setting, negating, and testing of bits. The 
bit count begins with zero. The bit number lies in the range from 0 to 31 and is 
internally masked by the processor with AND 31. 

The following numbering system applies: 0 is the lowest valued bit; with 4 
byte integer values 31 is the highest valued bit and at the same time the prefix 
bit (if the prefix bit is set in 2’s complement the number is considered nega¬ 
tive, otherwise it will be a positive number). 

The function BCLR sets the yth bit of the numerical expression x equal to 
zero. BSET sets bit number y of expression x equal to 1. BCHG sets bit y of x 
equal to 1, when it was previously 0 and equal to 0 when it was previously 
equal to 1. The functions BTST returns 1 (TRUE) when bit y of x equals 1 and 
0 (FALSE) when this bit equals 0. 


Example: 

x=BSET(0,3) 

PRINT x,BSET(0,5) 

The numbers 8 (2 A 3) and 32 (2 A 5) are displayed on the monitor. 
t|=ASC("x") 

PRINT CHR$(t|),CHR$(BCLR(t|,5)) 

When a key is pressed the letter and its corresponding upper case equivalent 
will be displayed on the screen (in lower case letters bit 5 is always set, eras¬ 
ing this bit changes the character into upper case). 


Numeric functions and strings 


4-19 




BCLR / BSET / BCHG / BTST 


s$="Testworcf 

FOR e%=1 TO LEN(s$) 

PRINT CHR$(BCHG(ASC(MID$(s$,e%)),5)); 

NEXT e% 

Displays "tESTWORD" on the screen, changes every upper case letter into 
lower case and vice versa. 
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SHL/SHR 


SHL(x,y) SHL&(x,y) SHL|(x,y) 

SHR(x,y) SHR&(x,y) SHR|(x,y) 

x.y: iexp 

These commands shift the contents of a numeric expression x by y bytes. 
Without the input of a special variable type a long word (4 bytes) will be as¬ 
sumed; with & word length (2 bytes) will be used and "I" will indicate byte 
length. The third letter of the command corresponds to the direction of the 
shift or rotation. The L indicates left and R indicates right 

With word functions (&) bit 15 is copied to bits 16 through bit 31 and with 
byte functions (I) bits 8 through 31 are erased. The following examples show 
the application of the shift command. 


x% 

SHL|(x,l) 

BIN$(x%,16) 

BIN$(SHL|(x%,l)*16) 

18 

36 

0000000000010010 

0000000000100100 

642 

4 

00000010 10000010 

00000000 00000100 

x% 

SHL&(x%,l) 

BIN$(X%,16) 

BIN$(SHL&(x%,1),16) 

18 

36 

00000000 00010010 

0000000000100100 

130 

4 

00000000 10000010 

0000000100000100 

x% 

SHR&(x%,2) 

BIN$(x%,16) 

BIN$(SHR&(x % ,2),16) 

24 

6 

00000000 00011000 

0000000000000110 

4162 

1040 

0001000001000010 

0000010000010000 


(The bits are shown in eights for clarity sake only, BINS does not group them like that.) 
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ROL/ROR 


ROL(x,y) ROL&(x,y) ROL|(x,y) 

ROR(x,y) ROR&(x,y) ROR|(x,y) 

x,y: iexp 

The operand length and direction are the same as with the shift command. For 
example, the highest bit of a byte is moved. This byte is now rotated to the left 
(ROLI( 128,1)). The left bit is now placed into the right part of the byte, so that 
the first bit of the byte is now set With SHLI(128,1) the bit that was pushed 
out would have become zero. 


X| 

ROL|(x,l) 

BIN$(x|3) 

BIN$(ROL|(x|,l)>8) 

6 

12 

00000110 

00001100 

130 

5 

10000010 

00000101 

x| 

ROR|(x|,3) 

BIN$(x|,8) 

BIN$(ROR|(x|,3),8) 

66 

144 

01000010 

00000000 

2 

64 

00000010 

01000000 


Example: 

x|=128+1 Isets Bit 7 and 0 

y%=ROR|(x|,1) !y becomes equal to 192 

PRINT SHL(y%.4),y%*2 A 4 
PRINT SHL(ROR|{ 128+1,1 ),4) 

The number 3072 is displayed on the screen three times. The expression a*2 A b 
corresponds to the function SHL(a,b), as long as no bits are pushed past the 
four byte length. The formula that the bit function uses is, however, much 
faster. 
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AND/OR/XOR 


AND(x.y) 

OR(x,y) 

XOR(x.y) 

x,y: iexp 

These functions logically combine two numerical expressions. Only bits that 
are set in both x and y are set in the result of an AND function. In the result 
from an OR function, the bit is set only when the corresponding bit is set in 
either x or y. XOR sets bits that are set in x or y but not in both, in other words 
XOR sets bits that have different values in x and y. 

Example: 


x=3 

y=2 

z=AND(x,y) !z becomes equal to 2 
PRINT OR(2,7),XOR(x, 1 +4+8) 

The numbers 7 and 14 are displayed on the screen. 
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IMP / EQV 


IMP(x,y) 

EQV(x.y) 

x,y: iexp 

IMP sets the bit to zero when the corresponding bit is set in x and not set in y. 
EQV sets a bit when the corresponding bits in x and y have the same value. 
Consider the truth tables in the section about logical operations. 


Example: 

PRINT BIN$(15,4),15 
PRINT BIN$(6,4),6 
PRINT BIN$(IMP(15.6),4),"IMP(15,6)“ 
PRINT BIN$(EQV(15,6),4),‘EQV(15,6)" 


The following is displayed on the screen: 

1100 15 
0110 6 

0110 IMP(15,6) 

0110 EQV(15,6) 
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SWAP 


SWAP(x) 

x: iexp 

The function SWAP accepts the expression x as a long word (4 bytes) and ex¬ 
changes the upper and lower words (two bytes at a time). This function has 
nothing to do with the GFA-BASIC command of the same name, they are used 
for different purposes. (For example to pass a long word parameter to a system 
routine as two words or in order to work with a pointer with exchangeable 
word order.) 


Example: 

X= 1044480 
PRINT B!N$(x,32) 
y=SWAP(x) 

PRINT BIN$(y,32) 

The following is displayed on the monitor: 

00000000000011111111000000000000 
11110000000000000000000000001111 
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BYTE / CARD / WORD 


BYTE(x) 

CARD(x) 

WORD(x) 

x: iexp 

BYTE returns the lower eight bits of the numeric expression x. CARD reads 
the lower 16 bits of x. WORD enlarges a word into a long word (that is, bit 15 
is copied into bits 16 through 31). 


Example: 

PRINT BVTE( 1 +254),BYTE( 1 +255) 

PRINT HEX$(CARD(&H1234ABCD)) 

Displays 255,0 and ABCD on the screen. 
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LEFTS / RIGHTS 


LEFT$(a$ [,X]) 

RIGHT$(a$ [,X]) 

a$: sexp 
x: iexp 

LEFTS returns x characters from the left side of the string a$. If x is larger 
than the number of characters in a$ then all of a$ is returned. Without x only 
the first character of the string a$ will be returned. RIGHTS returns the last x 
characters of the string a$. Without x only the last character of a$ is returned. 


Example: 

a$="Handbook for GFA-BAS1C" 
b$=LEFT$(’GFA Systemtechnik*,4) 

PRINT b$;RIGHT$(a$,5) 

The word "GFA-BASIC” is displayed on the monitor. 


a$=‘Ontario" 

b$=LEFT$(a$)+RIGHT$("Systemtechnik’) 
PRINT b$ 

"Ok" is displayed on the screen. 
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MID$ 


MlD$(a$,x [,y]) (as Function) 

a$: svar 
x,y: iexp 

The function MID$ returns y characters starting from the x position in the 
string a$. If x is larger then the length of a$ then an empty character string will 
be returned. If y is left out then the string after the xth character is returned. 


Example: 

a$=*Handbook for GFA-BASIC" 
b$=MID$(a$,14,9)+MID$CVersion 3.0",8) 

PRINT b$ 

"GFA-BASIC 3.0" is displayed on the screen. 
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MID$ 


MID$(a$,x [,y]) (as command) 

a$: svar 
b$: sexp 
x,y: iexp 

MID$ as a command makes it possible to place a string expression in the mid¬ 
dle of a string variable. In this manner MID$(a$,x,y)=b$ the string b$ is in¬ 
serted into the variable a$ starting at the xth position. The optional parameter y 
indicates the maximum number of characters from b$ to be placed in a$. If y is 
left out then as many characters as possible will be inserted. The length of a$ 
is not changed by MID$, but rather the characters from b$ write over the 
characters in a$. If a$ is too short to receive all of b$ then the transfer is 
stopped. 


Example: 


a$=’GF ASIC’ 

M!D$(a$,3)=*A B’ 
b$=’Testword' 

MID$(b$.6,2)=’who was that" 

PRINT a$,b$ 

The words "GFA-BASIC” and "Testword" are displayed on the screen. 
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INSTR 


INSTR(a$,b$) 

INSTR(a$,b$, [x]) 

INSTR([x],a$,b$) 

a$,b$: sexp 
x: iexp 

The INSTR function searches for a character string b$ within a string a$. If x 
is given then the search begins with the xth character, otherwise the search 
begins with the first character. A value is returned which is the position of the 
character after which the string b$ is contained. If b$ is not found then INSTR 
equals zero. When a$ and b$ are both spaces then INSTR equals one. 


Example: 

a$=‘GFA-Systemtechnik" 
x=INSTR(a$,"System") 

PRINT x, INSTR(’GFA-BASIC","BASIC",6) 

The numbers 5 and 0 are displayed on the screen. 
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RINSTR 


RINSTR(a$,b$) 

RINSTR(a$,b$, [x]) 

RINSTR( [x] ,a$,b$) 

a$,b$: sexp 
x: iexp 

RINSTRO searches a string like INSTR but this search begins with the RIGHT 
most character in the string, or the given position within the string. 


Example: 

PRINT RINSTR(-DFO:\FOLDER\TEST.GFA-.V) 

Searches for the last back slash 'Y in the path name and returns the position of 
the character (in this case 11). 
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STRINGS / SPACES / SPC 


STRING$(x,a$) 

STRING$(x,code) 

SPACE$(x) 

SPC(x) 

x.code: iexp 
a$: sexp 

The function STRINGS creates a string that contains the string expression a$ 
or the ASCII value code x times (between 0 and 32767). CHRS(code) is used 
with the input of "code". 

SPACES creates a string containing x blank spaces. SPC places x blank spaces 
in a PRINT command. In contrast to SPACES, the SPC command creates no 
string so that, for example, an equal sign can be assigned to a variable. 


Example: 

a$=“GFA * 
b$=SPACE$(5) 

PRINT b$;STRING$(3,a$);SPC(4);STRING$(5,'<") 

" GFA GFA GFA ««<" is displayed on the screen. 
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PRED/SUCC 


PRED(a$) 

SUCC(a$) 

a$: sexp 

PRED returns the character that is one ASCII value lower than the string ex¬ 
pression a$. Only the first character of the string is used in this process. In 
contrast to this SUCC returns the next higher ASCII value character. 
PRED(a$) corresponds to the expression CHR$(PRED(ASC(a$))) and 
SUCC(a$) the expression CHR$(SUCC(ASC(a$))). Both functions are avail¬ 
able for integer expressions also (see the section about integer arithmetic). 


Example: 

character$=‘B" 

previous$=PREDcharacter$) 

next$=SUCC(character$) 

PRINT previous$,character$,next$ 

Displays the letters A, B and C on the screen. 
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LEN / TRIM 


LEN(a$) 

TRIM$(a$) 

a$: sexp 

LEN returns the number of characters in the string a$. 

TRIMS removes empty spaces from the left and right of a string. 


Example: 


a$='Test’ 
x=LEN(a$)+1 
PRINT x,LEN(*Word*) 

The numbers 5 and 4 appear on the screen. 

b$=" test • 

PRINT LEN(b$) 

PRINT TRIM$(b$) 

PRINT LEN(TRIM$(b$)) 

Displays the number 10, the string "test'' without empty spaces and the number 
4 on the screen. 
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UPPERS 


UPPER$(a$) 

a$: sexp 

Changes all lower case characters into upper case characters. 
Example: 

a$=“Tesf 

b$=UPPER$(a$)+UPPER$("Wo*+'rd") 

PRINT b$;UPPER$(‘ GFA-BASIC 3.0') 

"TESTWORD GFA BASIC-3.0" is displayed on the screen. 
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LSET / RSET 


LSET a$=b$ 

RSET a$=b$ 

a$: svar 
b$: sexp 

LSET and RSET set the left (LSET) and right justification of the string b$ in 
which the length of the string a$ is not changed. 


Example: 

a$=" 

FOR i%=1 to 128 
LSET a$=STR$(i%) 
PRINT a$; 

NEXT i% 

PRINT 

FOR i%=1 to 128 
RSET a$=STR$(i%) 
PRINT a$; 

NEXT i% 


Iformats the left margin 


! and the right margin is formatted 
! number column is output 


Displays right and left margin formatted colons on the screen. Instead of 
RSET a$=STR$(i%) a$=STR$(i%,5,0) could be used. 
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5 - Input and output 
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INKEY$ 


INKEY$ 

INKEY$ reads a character from the keyboard. It is, however, not possible to 
read a keyboard control key (shift, Alt, Ctrl, Caps Lock). The function returns 
the ASCII code of the pressed key. With special keys, like the function keys, 
the corresponding CSI Sequence will be returned, which means a CHR$(155) 
followed by a number of additional characters is returned. 

The following example shows how to determine the value of a key with 
INKEYS. 


Example: 

DO 

t$=INKEY$ 

IF t$<>~ 

IF LEN(t$)=1 

PRINT "ASCII code: "ASC(t$),-ASCII character: -;t$ 
ELSE 

FOR i%=1 to LEN(a$) 

PRINT ASC(MID$(a$,f%)) 

NEXT i% 

PRINT 

ENDIF 

ENDIF 

LOOP 


Displays the ASCII code or CSI sequence of every key that is pressed. 
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INPUT 


INPUT ["text",] x [,y,.„] 

INPUT ["text";] x [,y,...] 

x,y: avar or svar 

The command INPUT can be used in many variations. It serves to input vari¬ 
ables of variable lists with or without an input prompt ("text"). INPUT is al¬ 
ways executed in a window. If no window is already open within the program, 
window 0 with the standard size will be automatically opened. 

The prompt is always positioned at the last cursor position. With the help of 
PRINT AT followed by a semicolon or LOCATE, VTAB, HTAB the cursor 
can be placed accurately at the desired position. 

When the command INPUT is followed by an input prompt it can be separated 
from the input variable by a comma or semicolon. If a semicolon follows the 
input prompt string, a question marie and a space will be displayed. If a comma 
is used then the cursor will be placed directly behind the input text. 

If no text string is behind the command INPUT then a question mark will ap¬ 
pear followed by a blank space and the cursor. 

If only one variable is to be entered then the RETURN or ENTER key must be 
pressed to acknowledge the input. 

If several variables are to be entered with only one INPUT command then 
each variable can be separated by pressing the RETURN or ENTER key, they 
can also be separated by a comma between each variable, and then acknow¬ 
ledged with a single press of either the RETURN or ENTER key. 

To enter commas within a string the command LINE INPUT must be used. 
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INPUT 


If a numerical variable is expected and text is entered instead, an error beep 
will be heard and the input must be repeated. Until the RETURN or ENTER 
key is pressed the characters within the input can be erased by using the back¬ 
space, and the DELETE key; the left and right cursor keys are also active. 


Example: 

OPENW 0 
INPUT a$ 

INPUT ",b$ 

INPUT "Two numbers please: “;x,y 
PRINT a$,b$,x,y 

Reads two strings and two numerical variables. The first INPUT command has 
the prompt"?", the second with no text and the third with the text "Two num¬ 
bers please: ?". 
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LINE INPUT 


LINE INPUT; ["text",] a$ [,b$...] 

LINE INPUT ["text";] a$ [,b$...] 

a$,b$: svar 

LINE INPUT is a variation of the INPUT Command. In contrast to INPUT it 
is possible to include commas in a string variable. The editing during input of 
variables or variable lists, before the RETURN or ENTER key is pressed, is 
the same as with INPUT. 


Example: 

OPENW 0 
LINE INPUT a$ 

INPUT b$ 

PRINT a$,b$ 

Please enter the text "Com,ma" twice. After this the text "Com,ma" and "Com" 
will be displayed on the monitor. 


Compare to LINE INPUT# (Chapter 6). 
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FORM INPUT 


FORM INPUT n,a$ 

FORM INPUT n AS a$ 

n: exp 
a$: svar 

FORM INPUT and FORM INPUT AS both serve to input string variables. ”n" 
is the number of characters the string a$ may contain (between 1 and 255). 

FORM INPUT AS prints the current value of a$ which can then be edited. The 
editing options for both commands are the same as with the INPUT command. 


Example: 

FORM INPUT 10,a$ 
b$="test" 

FORM INPUT 5 AS b$ 

PRINT a$,b$ 

Asks for the input of two strings. With the input of the second string the word 
"test" is given as the current value of b$. 
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PRINT 


PRINT 

PRINT expression 
PRINT AT(column,line);expression 
WRITE expression 
LOCATE line.column 

expression: any sexp or aexp or in any combination 

column,line: iexp 

The command PRINT and its variations initiate screen output. With the Amiga 
it is very important that a window is open. When this is the case the output 
will be displayed in the last window opened with the OPENW command. Nor¬ 
mally a standard window will be opened. The command PRINT with no addi¬ 
tional parameters will initiate a line scroll. If the cursor is in the last line the 
entire screen will be scrolled up one line. PRINT followed by an expression 
causes the expression to be displayed at the current cursor position. Strings 
must be enclosed in quotation marks. If the expression to be displayed is made 
up of many elements (constants, variables or expressions), it can be separated 
by a semicolon, comma or apostrophe. 

By using a comma the cursor is placed on the next of the 16 column positions. 
If the last column is reached the cursor is placed in column 17 of the next line. 
The semicolon leaves no space between the corresponding elements. If an 
apostrophe is used a space is inserted between the corresponding elements. 

PRINT AT makes it possible to place the expression at a certain row and 
column. For this there are 80 columns and 5 lines depending on the screen 
resolution. When the output expression does not end with a semicolon then the 
cursor will be placed at the beginning of the next line. When the cursor is al¬ 
ready on the last line then the screen will be scrolled up one line. 
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PRINT 


In contrast to PRINT AT, LOCATE sets the cursor at the given line and 
column position. It is not possible to output expressions with LOCATE (refer 
to VTAB/HTAB). 

The WRITE command serves to save data in a sequential file to read this data 
back with input. After the WRITE command there are numerical and string ex¬ 
pressions, these are separated by commas. 

In the output the expressions are separated by commas; string expressions are 
contained in quotation marks. 

NOTE: this format is specifically for the reading of data with INPUT. Behind 
the last expression of a WRITE command a semicolon can also be found. 
When this is the case the final expression will be suppressed with a CR/LF. 


Example: 

OPENW 0 

a$="GFA-Systemtechnik" 

PRINT Left$(a$,4)+"BASIC"1+2; 

PRINT ".0","GFA-";UPPER$(MID$(a$,5)) 

the text GFA-BASIC 3.0 and GFA-SYSTEMTECHNIK are displayed on the 
screen. 

PRINT AT(4,8);'ln the fourth column of the eighth line" 

Displays a string at the position 4,8. 

LOCATE 8,4 

PRINT "in the eighth line, of the fourth column" 

Positions the cursor at the fourth column of the eighth line and outputs a string 
at this position with the PRINT command. 

WRITE 1+1, "Hello",3*4 

Displays the expression 2",Hello", 12. 
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PRINT USING 


PRINT USING formats,expression!;] 

PRINT AT(column,llne);USING formats,expression!;] 

format$: sexp 

expression: as many sexp or aexp or any combination as desired 

column,line: iexp 

PRINT USING and its variation PRINT AT USING serve to format data out¬ 
put to the screen. Fundamentally these commands work like PRINT and 
PRINT AT. However the contents of the expression to be displayed are put into 
the format specified by formats. 

The following characters are available to format numerical expressions. 

# Place holder for one numeric character; if this is the last character in 
the format string, then the result will be rounded here. 

, Serves to separate the decimal numbers within many #-characters. 

Inserts a decimal at any position within a group of #-characters and 
separates the thousandths place. 

The minus sign can only be at the first position of the format string. It 
reserves a place for the output of a negative sign. With a positive sign a 
blank space is left here. 

+ In contrast to the minus sign if a positive sign is placed here then the 
number is positive. Plus and minus signs can not be combined. 

* Can only be located in the first position of the format string. It replaces 
an empty space by placing the asterisk instead of a space. 

$ Initiates the output of a $ character before the numerical output when it 
is directly before the first # character. 
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PRINT USING 


Serves to set the exponential format (E+000). With the # characters set 
the length of the Mantissa (including the character E and +). There may 
only be one # character in front of the decimal. 


To format character strings the following characters are available: 

& Initiates the output of the entire string. 

! Reduces the output to the first character of the string. 

V.\ Sets the number of characters (including both \ characters) of a string 
that are to be displayed. 

The underscore initiates the output of the format characters. Further¬ 
more the unmodified output of text insertions between these formats is 
possible. The format string is followed by the variables or variable list 
or expression are seperated by commas. 


Example: 

OPENW 0 

PRINT USING "#.####",PI 

PRINT AT(4,4); USING ’Pl_._._. #.###‘,PI; 

The text "3.1416" and "PI... 3.142" are displayed on the screen. 


FOR i%=1 TO 14 
PRINT USING "###;## AAAA *,2 A i%; 
NEXT i% 


Output: 


1.00E+00 

16.00E+00 

256.00E+00 

4.10E+03 


2.00E+00 

32.00E+00 

512.00E+00 

8.19E+03 


4.00E+00 

64.00E+00 

1.02E+03 

16.38E+03. 


8.00E+00 

128.00E+00 

2.05E+03 
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MODE 


MODEn 

n: iexp 

Through MODE, decimal points and commas denoting thousands as well as 
decimal commas and points denoting thousandths can be exchanged. Besides 
this, the format of the date presentation can be selected. Points and commas 
are used for PRINT USING and STR$(x,v,n). The date setting applies to 
DATES, SETTIME, DATE$=and FILES. 

The parameter n can contain values between 0 and 3. For this the following 
table applies: 

parameter n USING DATES 

MODEO ,###.## 16.05.1988 

MODE 1 #,###.## 05/16/1988 

MODE 2 #.###,## 16.05.1988 

MODE 3 #.###,## 05/16/1988 
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DEFNUM 


DEFNUM n 

n: iexp 

DEFNUM defines numeric output for the PRINT command and its variations. 
All numeric output after a DEFNUM command is printed with n places 
(before and after the decimal, the decimal is not counted). The internal resolu¬ 
tion of the number is not changed. The number is rounded at the n+lth place. 


Example: 

OPENW 0 
PRINT 100/3 
DEFNUM 5 
PRINT 100/3 

The numbers 33.333333333 and 33.333 are displayed on the screen. 
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CRSxxx / POS / TAB 


CRSCOL 

CRSLIN 

POS(x) 

TAB(n) 

HTAB column 
VTAB line 

n,column,line: aexp 

x: aexp 

The command group CRSCOL, CRSLIN, POS and TAB serve to determine 
and set the position of the cursor. CRSCOL returns the current column posi¬ 
tion and CRSLIN the current line position of the cursor. POS returns the num¬ 
ber of times the character AND 255 has been output to the screen since the last 
carriage return. The expression x is ignored. 

The position value returned from POS may not necessarily be the current cur¬ 
sor position. If, for example, a string with 120 characters is input then the cur¬ 
sor will be in column 40, POS returns the value 120. POS(0) has little to do 
with the column position output of control characters, because only the charac¬ 
ters are counted. A LF (CHR$(10)) is not noticed, a CR(CHR$(13)) resets the 
counter to null, and a BS (CHR$(8)) decrements the counter by 1. 

TAB(n) outputs null characters until POS(O) reaches the value of n. If n is ex¬ 
ceeded, then the next carriage return (CR/LF) will be executed like with a 
print without parameters. Again only AND 255 is applied. 

The commands HTAB and VTAB position the cursor at a certain place in the 
column or line. When positioning the cursor, the upper left comer of the win¬ 
dow has the coordinate 1. 
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CRSxxx / POS / TAB 


Example: 

PRINT AT(38,12);'Test *; 

PRINT CRSCOL'CRSLIN 
PRINT TAB(37);’Test •; 

PRINT POS(O) 

The text "Test 42 12" and "Test 41" are displayed in the middle of the screen. 

PRINT AT{4,3);‘Word 1” 

HTAB 4 
VTAB 2 

PRINT "Word Y 

Displays the text "Word 1" at the fourth column of the third line and "Word 2" 
in the fourth column of the second line. 
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DATA 


DATA const [,const1,const2,...] 

READ var [,varl,var2,...] 

RESTORE [name] 

const,constl ,const2: numeric or string constant 
var.varl ,var2: avar or svar 

name: user defined name 

With the help of the DATA command, constant values can be economically 
entered. This data is read with READ. The numerical values can be entered in 
hexadecimal, octal, or binary form. When a string that contains a comma is to 
be read in, the entire string must be enclosed in quotation marks. 

A data pointer is associated with the commands DATA and READ. This 
pointer always points to the next DATA item to be read with the READ com¬ 
mand. When the program begins, this pointer is set to the first value behind the 
first DATA line. The data pointer can be set at a specific DATA line with the 
RESTORE command. For this purpose, a label must be set in front of the 
DATA line and the data pointer set with RESTORE label. If no label follows 
the RESTORE command the data pointer will be set to the first DATA item in 
the program. 

The label can be made up of numbers, letters, underscores, and periods, and, in 
contrast to a variable name, may start with a number. The label must end with 
a colon. 
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DATA 


Example: 

OPENW 0 
FOR i=1 TO 3 
READ a 
PRINT a' 

NEXT i 

RESTORE roman_numbers 
READ a$,b$,c$,d$ 

PRINT 

PRINT aS’bS’cS’dS 

DATA 1,2,3,4 
DATA a,b,c,d 

roman_numbers: 

DATA I,II,III,IV 

The numbers 1,2, and 3 are read in a loop and shown on the screen. After this 
the pointer is set to the DATA line containing the roman number characters 
using the RESTORE command. The line is marked with the label roman_num- 
bers. The example is finished with this data being assigned to the string vari¬ 
ables a$, b$, c$ and d$ and then output to the screen. 

DATA 10,&A,&A,&HA,&012,&X1010,%1010 
FOR i%=1 TO 7 
READ a% 

PRINT a% 

NEXT i% 

Reads the number 10 seven times. With READ/INPUT/VAL etc. HEX num¬ 
bers can be read in using a $ before the number and BIN numbers using a % 
before the number. 
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MOUSE 


MOUSE mx,my,mk 
MOUSEX 
MOUSEY 
MOUSEK 

The command MOUSEX, MOUSEY and MOUSEK make it possible to read 
the current mouse position and the current mouse button status. With the help 
of the MOUSE command these can be read in together. MOUSE returns the 
current mouse position in mx and my and the current mouse button status in 
mk. The variable mk can contain values from 0 to 7. 

mk Pressed key 

0 None 

1 Left mouse button 

2 Right mouse button 

3 Left and right mouse button 

4 Middle mouse button 


With further combinations of the above settings mk will contain the sum of the 
individual values. 

The coordinates returned are always in relation to the current output window. 
If the mouse is outside the window area negative coordinates will be returned. 
If the command is executed without a window being previously opened mx 
and my will contain the value 0. 
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MOUSE 


Example: 

OPENW 0 
REPEAT 
IF MOUSEK=1 
PLOT MOUSEX,MOUSEY 
ENDIF 

UNTIL MOUSEK=2 
REPEAT 

MOUSE mx%,my%,mk% 

IF mk%=2 
PLOT mx%,my% 

ENDIF 

UNTIL mk%=1 

The mouse position and mouse button status is read in the REPEAT loop. 
When the left mouse button is pressed a point will be drawn at the current mx, 
my coordinates. The loop is exited when the right mouse button is pressed. In 
the second loop points can be drawn with the right mouse button and the loop 
can be exited with the left mouse button. 
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LPRINT / LPOS 


LPRINT expression 
LPOS(x) 

expression: aexp or sexp or any combination 
x: avar, position 

LPRINT expression makes the output of data to the printer possible. LPRINT 
is identical to the PRINT command. Basically all PRINT command variations 
can be used. The print head cannot be positioned using PRINT AT(x,y), but 
LPRINT USING will position it. 

LPOS(x) returns the number of characters output to the printer since the last 
CR (refer to POS(x)). 


Example: 

LPRINT 
LPRINT'Test' 

PRINT LPOS(x) 

Executes a line feed on a printer (if one is connected and turned on), writes the 
word "Test" to the printer and shows the current position of the printer head to 
the screen. 
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HARDCOPY 


HARDCOPY 

HARDCOPY [adr,comap,modes,srcx,srcy,srcw,srch,destc,destl, 
spec] 

adr, comap, modes, srcx,srcy,srcw,srch,destc,destl,spec: iexp 

HARDCOPY without parameters initiates a graphic output of the current win¬ 
dow or Rastport to the printer. The printer settings from the system preferences 
are used. If another window is opened after a Rastport an error message will 
be displayed. The optional parameters can be given in order to change the out¬ 
put. 

adr: Address of the rastport from which the hard copy is to be made. 

comap: Address of the color map containing the colors of the picture. 

modes: The resolution mode as they are given in the viewport structure. 

srcx: Offset to the left edge of the Raster port. 

srcy: Offset to the right edge of the Raster port. 

srcw: The width of the printed area. 

srch: The height of the printed area. 

destc: Number of columns to be printed. 

destl: Number of lines to be printed. 

spec: Tells how the parameter "destc" and "destl" are to be evaluated. 

If bit 0 is set then the input in "destc" is set to thousandths of an 
inch, with bit 1 having the same meaning for "destl". Bit 2 
means the maximum line width when it is set Bit 3 means the 
maximum height. Bit 4 means that "destb" is a part of the maxi¬ 
mum width. Bit 5 corresponds to the height Bit 6 (64) means 
that the printed picture output will be centered. Bit 7 means 
that the page directory corresponds to the paper on the screen. 
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HARDCOPY 


The quality of the print out can be set in bits 8 through 10. For 
example &hl00 for the lowest resolution of the printer and 
&h700 for the highest. A set bit 11 disables the form feed at the 
end of the output The default spec is &h84, and that means full 
width with the page contents. 


Example: 

OPENW 2 

GRAPHMODE 1 

COLOR 1.2,1 

DEFFILL 1,3,12 

PBOX 10,10,100,100 

HARDCOPY LPEEK(adr%+50) 

Prints a workbench screen with a BASIC window. 
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SOUND / WAVE 


SOUND freq,duratlon[,vol[,chan]] 

WAVE chan,wave() 

freq,duration,vol,chan: iexp 

wave(): integer field (%, & or |) or sin() 

With the commands SOUND and WAVE the four noise generators of the 
Amiga can be controlled. The first parameter of the SOUND command deter¬ 
mines the frequency of the tone as in the following table: 

Note Frequency in hertz 
C 261.6 

D 293.7 

E 329.6 

F 349.2 

G 392.0 

A 440.0 

H 493.9 

For each higher octave the frequency is doubled, for lower octaves the fre¬ 
quency is halved. 

The second parameter determines the duration. This 16 bit number determines 
how many sine waves are to be repeated for the tone. 

The parameter "vol" can set the volume between 0 and 255. If "vol” is missing 
the middle volume (127) is used. 

The last parameter ("chan") sets which channel the tone is to be sent through. 
In this 0 and 3 are used for the left speaker and 1 and 2 for the right speaker. 
The default is "0" 

With the WAVE command individual waves can be set for each channel. The 
default is a sine wave, which can also be set using the keyword SINO- Nor¬ 
mally 256 byte values will be in the integer array wave% that will create cover 
form. This field can also be a long word integer (%), a word integer (&) as 
well as a byte integer (I). 
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6 - Disk handling and file organization 


Disk handing and file organization 
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File specification 


In this chapter, the commands used for file organization are explained. In the 
construction of file specifications the rules of the hierarchical file system must 
be known. A file specification is made up of three parts: the specified drive, 
the file name, and the extension. The drive specification contains the drive 
identification (DFO...), followed by a colon. The file name can contain a maxi¬ 
mum of 30 characters. 

Directories (also called folders) are used for further subdivision of files to help 
further organize data. These directories can be set in different levels; the 
lowest level is called the root directory. Other directories can be branched out 
to from this root directory. A directory entry can be made up of these three 
parts: 


- Drive specification 

- Name of the directory and sub directories 

- File name 


These parts are separated by slashes Names of directories have the same 
format as file names. Therefore the access path to a directory is made up of 
combinations of previously defined elements of the name. First the drive iden¬ 
tification, followed by the name of the directory, and then the file name, for 
example DFO:TEXT/HANDBOOK/CHAPTER_1. In this example the access 
path is: 


DFO: 

TEXT 

HANDBOOK 
CHAPTER. 1 


drive identification 
directory 

sub-directory HANDBOOK 
file name CHAPTER. 1 


In addition to this there are two special characters available, that will enable a 
simpler selection of a file. These characters can be included in the file name or 
its extension. They are the question mark and the asterisk (multiplication sym¬ 
bol). The question mark makes it possible (for the position it occupies) to con¬ 
tain any ASCII code larger than 32. It is also possible to use the question mark 
in many positions of the file specification, or to use many in sequence. The 
asterisk means that any character can occupy the remaining positions in the 
file specification. 
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Random access 


Operation of the so called Random access file (file with random access) will 
also be explained. Two concepts are extremely important: record and field. 

A record represents a logical combination of fields, for example the record 
"address". This record can be divided into fields, for example "name" and 
"street". Similar to these concepts are the record and field length. You must 
give the length of the record and field in bytes. 

The most obvious difference between a random access file and a sequential ac¬ 
cess file is in the access method. With a sequential file the entire file must be 
loaded into the computer in order to access one field. In a random access file, 
however, one record can be read into the computer without having to read in 
the entire file. This is especially useful for very large files. 

The disadvantage is that a larger file area is required on the disk. A random ac¬ 
cess file works with a set file length. The length of the file is not dependent on 
the length of the actual data in a record or field. 
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CHDIR / DIR$ / DFREE 


CHDIR name$ 

DIR$(n) 

DFREE(n) 

name$ :sexp 

DIR$(n) determines the current path for a drive. The whole path, including the 
drive id, is returned. "0" is a dummy parameter and has no function. DFREE 
(disk free) returns the free memory space remaining on the disk in bytes. 

CHDIR sets the current directory. The expression name$ specified the desired 
path. The conventions used for path change in CLI apply also to name$: 


dfO: 

dhOidevs/printers 

/ 


:devs 


changes the drive id in the main directory 
changes the directory (devs/printers) no a hard disk 
jump a level up in the directory tree. Note: the root direc¬ 
tory is the highest level 
changes the drive id in the current directory 
changes the directory "devs" in the root directory 
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CHDIR / DIR$ / DFREE 


Example: 

CHDIR 

CHDIR -TEXT_DOC/HANDBOOK- 
CHDIR -APPENDIX - 
CHDIR *:* 

Changes the key directory of the current drive. In the second line to the folder 
HANDBOOK of the directory TEXT_DOC. In the third line it is changed fur¬ 
ther in the sub directory APPENDIX (TEXTJXJC/HANDBOOK/APPEN- 
DIX). 
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DIR / FILES 


DIR p$ [TO name$] 

FILES p$ [TO name$] 

p$,name$: sexp 

The commands DIR and FILES serve to output a directory. When DIR is used 
the contents of a specific directory is shown in a window. The desired access 
path is given in the string expression p$. The use of wild cards is not allowed. 
The same applies to the FILES-Command except that the date, time and length 
of the file is given. Furthermore, all directories at the current level are also 
given. 

For DIR and FILES the optional input of an additional TO name$ is possible. 
The application of this additional parameter makes it possible to route the out¬ 
put of the directory contents to a file or peripheral device. The string expres¬ 
sion name$ contains the name of a data or peripheral device. 


Example: 

DIR -DFO:-WORD_PROCESSING- 

DIR ’DFO:-WORD_PROCESSING- TO "DF1 :"MANUAL\CONTENTS.ASC" 

DIR "DF0:“ TO 'PRT:* 

In the first line all file names in directory "WORD_PROCESSING" on disk in 
drive DFO are displayed on the screen. The second line saves the contents as a 
file "CONTENTS.ASC" to drive DF1. The output to printer is illustrated on 
the third line. 
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EXIST 


EXIST(name$) 

name$: sexp 

With the help of EXIST we can verify if a file is available. The string expres¬ 
sion name$ contains the path to this file. The function returns TRUE (1) when 
the file exists, otherwise it returns FALSE (0). 

Example: 

OPEN “U",#1,"TEST.TXT" 

PRINT #1,“EXAMPLE- 
CLOSE #1 

PRINT EXIST(“TEST.TXT“) 

PRINT EXISTCTEST.DOC") 

In the first three lines a file with the name "TEST.TXT" is opened, the fourth 
line checks for the availability of the file "TEXT.TXT", TRUE is returned. In 
the last line the check returns FALSE, because the file does not exist. 
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OPEN 


OPEN; mode$, [#] n,name$ [num] 

mode$,name$: sexp 
num.n: iexp 

OPEN opens a file channel to a file or to a peripheral device. The string ex¬ 
pression "mode$" sets the access options: 


O (output) 

I (input) 

A (append) 

U (update) 

R (random access) 


Opens a file to be written to. With this, the previously 
created file is erased. 

Opens a file for reading 

Makes it possible to add data to a created data file. With 
this the data pointer is set to the end of the data. 

Opens an existing file for writing and reading. 

Opens a random file for writing and reading. A descrip¬ 
tion of this file type is given under the Field command. 


The numeric expression n contains the channel number and can have the value 
from 0 to 99. This channel number must be given when working with the file. 
With this the character of the channel number can be left out. The string 
expression name$ contains the path to the file. A peripheral device can also be 
given as the file name (see list with 1NP). The numeric expression num is 
given with random access data; it contains the length of the data string. 


Abbreviation 
LST: (list) 

AUX: (auxiliary) 
CON: (console) 
PRT: (Printer) 


Meaning 

Parallel 

Serial (RS 232) 

Keyboard/screen 

Printer 
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LOF/LOC/EOF/CLOSE/TOUCH 


LOF(#n) 

LOC(#n) 

EOF(#n) 

CLOSE [#n] 

TOUCH [#] n 

num, n:iexp 

The functions LOF (length of file), LOC (location) and EOF (end of file) can 
only be used with file that has previously been opened with OPEN. All three 
functions have a numeric expression n in common. The n is the channel num¬ 
ber of the file the function will access. LOF delivers the length of the file in 
bytes. LOC returns the current position of the data pointer (see also SEEK). 
EOF tells if the data pointer is pointing to the end of a file (for example, if a 
file has already been read). When the data pointer is at the end of the file then 
TRUE (-1) will be returned, otherwise FALSE (0) will be returned. 

CLOSE closes a data channel to a file or peripheral device that was previously 
opened with the OPEN command. The numeric expression n contains the 
number of the data channel to be closed. When no data channel is specified 
then all data channels are closed. 

TOUCH updates the time stored as part of the directory entry on the disk. 


Example: 

OPEN ”0‘,#1,"test.txt" 

FOR i%=1 TO 20 
PRINT #1 ,STR$(i%) 

NEXT i% 

CLOSE #1 
FILES "test.txt" 

DELAY 20 I 20 Second Pause 

OPEN "u",#1,“test.txt" 

TOUCH #1 
CLOSE #1 
FILES "test.txt" 
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LOF / LOC / EOF / CLOSE / TOUCH 


A data file named "test.txt" is opened under channel 1, written to and closed. 
This is followed by the output of the data to the screen, after a 20 second pause 
the file is given the current date and time and output once again. 

OPEN T,#l,"test.txt* 

PRINT * Data length: ";LOF(#1) 

PRINT 

PRINT " Data’,"Position of the data pointer" 

DO UNTIL EOF(#1) 

INPUT #1,a$ 

PRINT " ";a$.LOC(#1) 

LOOP 
CLOSE #1 

The example opens the same data file to be read. First, the length of the data 
file is determined with LOF. Then the contents of the data and the appropriate 
data pointer are printed to the screen. The loop exit criteria is set with EOF. 
Reading of the data is accomplished by checking the data pointer to be sure 
the file has not come to the end (this is done independently of the length of the 
file) The loop will repeat until the function EOF is TRUE (-1). 


6-10 


GFA-BASIC 3.0 Amiga 



NAME / RENAME / KILL 


NAME old$ AS new$ 

RENAME old$ AS new$ 

KILL name$ 

old$,new$,name$: sexp 

NAME renames a file with the path and name specified by old$, giving it the 
name new$. The contents of the file are not changed. Both files must be on the 
same disk. RENAME corresponds to the command NAME. 

KILL erases a file whose access path is specified by name$. 


Example: 

''OPEN "0",#1,“test.txt" 

PRINT #1 ."Example" 

CLOSE #1 

NAME "testtxt" AS "example.txt* 

DIR 

KILL "example.txt" 

DIR 

The data "testtext" is opened to be written to in the first part of the example. 
This is followed by the data being renamed "example.txt" and finally erased. 
This is checked by displaying the directory (DIR) on the screen. 
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BLOAD / BSAVE / BGET / BPUT 


BLOAD n$ [,adr] 

BSAVE n$,adr,num 
BGET #n,adr,num 
BPUT #n,adr,num 

ame$: sexp 

n.adr.num: iexp 

An area of Memory can be saved to disk (RAM disk. Hard disk, etc.) using 
BSAVE, this hie can then be loaded with BLOAD. The numerical expression 
adr gives the beginning address of the memory area to be saved. When no adr 
is specified, the last address given with BSAVE will be used. The expression 
num (the length of the data n$) must also be used with BSAVE. The parameter 
n$ is the name of the data file to be loaded or saved. The regulations described 
under DIR concerning the hierarchical data systems apply to the parameter n$. 

BSAVE, and BLOAD can access only the entire file. In contrast to BPUT and 
BGET which go through their channel numbers n. Thus it is possible to access 
only parts of a file with BGET and BPUT. 


Example: 

DATA 1,2,3,4,5.67.8.9,0 

a%=MALLOC( 12,0) 

FOR i%=0 TO 9 
READ b% 

POKE a%+i%,b% 

NEXT i% 

BSAVE ’DATABLOCK-,a%,10 
b%=MFRE E(A%, 12) 

Saves the data block under the name DATABLOCK on disk in the current 
drive. 


6-12 


GFA-BASIC 3.0 Amiga 




INP / OUT 


INP(#n) 

OUT #n,a [,b,c,...] 

n,a,b,c,...: iexp 

INP(#n) reads one byte from a previously opened data channel. OUT writes 
one byte to an opened data channel. The numerical expression n contains the 
channel number (0 to 99) from which the data can be accessed. 


Example: 

OPEN ■0",#1,‘test.txr 
OUT #1,128 
CLOSE #1 

OPEN T,#1,’test.txt" 
a=INP(#1) 

CLOSE #1 
PRINT a 

In the first example a file is opened for writing and a byte is written to it in the 
second example this byte is read into the numeric variable "a" and output to 
the screen. The variable "a" contains the value 128. 
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1NPUT$() 


INPUT$(num [,#n’) 

n, nutn:iexp 

INPUTS reads a character string made up of num characters from the 
keyboard. Specifying a channel number is optional with the parameter n (0 to 
99) and will read data from a file. In both cases the numeric expression num 
gives the number of characters to be read. 


Example: 

OPEN "0*,#1 ,"versk>n.dat* 

PRINT #1 ,'GFA-BASIC, Version 3.0* 

CLOSE #1 

OPEN T.#1.“version.dat* 
v$=INPUT$(9,#1) 

CLOSE #1 
PRINT v$ 

PRINT "Please input the version number: 

PRINT INPUT$(3) 

In the first example the file "version.dat" is opened and a message is written 
into the file. The second part of die example reads the first 9 characters of this 
data into the string variable v$ and finally outputs this to the screen. After this 
a message appears and 3 characters from the keyboard are read and output to 
the screen 
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INPUT # / LINE INPUT 


INPUT #n,var1 [,var2,var3,...] 

LINE INPUT #n,al$ [,a2$,a2$,...] 

n: iexp 

a1$, a2$, a3$: sexp 

varl, var2, var3: avar or svar 

INPUT #n makes it possible to read individual data from a data file. Individual 
values or variable lists can be read, as long as the variables are separated by a 
comma. A more exact description follows under INPUT and LINE INPUT. 

Example: 

OPEN T,#1,TEXT.DOC" 

INPUT #1 ,a$,b$ 

LINE INPUT #1,c$ 

CLOSE #1 
PRINT a$ 

PRINT b$ 

PRINT c$ 

Reads a string from a file that must have been previously opened and outputs 
it to the screen.. 
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PRINT # / WRITE # 


PRINT #n,expression 

PRINT #n, USING form$,expression 

WRITE; #n, expression 

n: iexp 

form$: sexp 

expression: aexp or sexp or any combination of the two 

PRINT #n outputs data through a data channel. PRINT #n, USING allows the 
formatted output through a data channel. In both cases the numeric expression 
n stands for a data channel number (0 to 99) of the corresponding file. Mostly 
like PRINT and PRINT USING. However PRINT #n, AT(,) is not possible. 

The command WRITE serves in the front line to help save memory area when 
data is saved in sequential form, and is used in combination with the INPUT 
Command. The expressions are separated by a comma, and character strings 
must be enclosed in quotation marks. 


Example: 

OPEN -0-,#1 .TEXT.DOC- 
b$="word" 

PRINT #1,’Tesr,a$ 

PRINT #1,*GFA -.-BASIC- 
CLOSE #1 

Writes three strings to the file created. 

OPEN -0-,#1,-TEST.DAT- 
WRITE #1,'Version',3.-.0- 
CLOSE #1 

OPEN -I',#1,-TEST.DAT- 
INPUT #1,v1$,v2$,v3$ 

CLOSE #1 

PRINT v1$+v2$+v3$ 

Writes data separated by a comma to the file TEST.DAT, and then reads the 
data again with INPUT and outputs it to the screen. 
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STORE / RECALL 


STORE #l,x$()[,n[TO z]] 

RECALL #l,x$(),n[TO z],x 

i,n,z: iexp 

x$(): string array 

x: variable, at least 32 bits 

The command STORE serves to save a string array as a text file (with separa¬ 
tion through LF). The complete string array is output through the opened chan¬ 
nel i. The selectable parameter n can contain the number of elements of the 
suing that should be saved. With n TO z a partial array can be saved (or 
loaded). 

The command RECALL serves to quickly read a string array from a text file, n 
lines of the text file are read into the string array. If n is too large for the string 
array dimension then the amount of data read in is automatically limited (n=l 
reads the entire array). 

If the end of the file is reached (EOF) then the input of data is ended with no 
error message. In each case the variable x contains the number of the strings 
read. 
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STORE/RECALL 


Example: 

DIM A$(1000) 

FOR i%=0 to 499 
a$(i%)=STR$(RND) lor something 
NEXT i% 

OPEN "0",#1,"testfile.txt" 

STORE #1,a$(),500 
CLOSE #1 

ERASE a$() 

DIM b$(2000) 

OPEN T,#1,"testfile.txt* 

RECALL #1,b$(),-1,n 

CLOSE 

PRINT n 

The number of text lines that were output is read, here 500. 

PRINT "Line counter" 

DIM a$(1000) 

DO 

FILESELECT "Counting lines","OK",*",f$ 

EXIT IF f$="“ 
lc%=0 

OPEN T,#1,f$ 

DO 

RECALL #1,a$(),-1,x% 

ADD lc%,x% 

LOOP WHILE x% 

CLOSE #1 

PRINT f$;" contains *;lc%;" lines." 

LOOP 

This program counts the number of lines in a text file. 
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SEEK / RELSEEK 


SEEK #n,pos 
RELSEEK #n,num 

n,num,pos: iexp 

The commands SEEK and RELSEEK make it possible to position the data 
pointer. It is possible to define an index sequential file access. The numeric ex¬ 
pression n contains the channel number of a file previously opened with the 
OPEN command. Both commands can only be used with data files, not with 
peripheral devices. The data pointer returns the byte that was last read or writ¬ 
ten. Except with Mode "A” (append) the data pointer will have the value 0 
when a data file is opened. The write and read commands begin with the first 
byte on which the pointer is placed. 

The absolute positioning of the data pointer is accomplished with the SEEK 
command. The data pointer will be placed at the "pos" byte. The relative 
pointer positioning takes place with the RELSEEK command. The data pointer 
is moved from its current position to the ”num" value position. The numerical 
expression "num” and "pos" may only be values from 0 to the length of the 
data file. With positive values the pointer is moved in the direction of the end 
of the file, with negative values the pointer is moved in the direction of the 
beginning of the file. 


Example: 

OPEN "O'.tl.’X.X' 

PRINT #1,STRING$(20,42) 

SEEK #1,10 

PRINT #1 

RELSEEK #1,-5 

OUT #1,33,48 

CLOSE #1 

OPEN V,#1,"X.X* 

LINE INPUT #1,a$ 

PRINT a4 
CLOSE #1 


Output’ *******iq************ 
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FIELD 


FIELD #n,num AS set$ [, num AS set$, num AS set$,...] 

FIELD #n,num AT(x) [,num AT(x) [,num AT(x) [„...] 

n, num.x: iexp 

set$: svar, but not a field variable 

The command FIELD AS subdivides records into fields. The numeric expres¬ 
sion n is the number of the data channel (0 to 99) of a data file previously 
opened with OPEN. Each open data channel may only have one FIELD com¬ 
mand. The whole number expression num sets the field length. The string vari¬ 
able set$ takes the record. If the record contains many fields then the com¬ 
mand (num AS set$) must be separated by commas. The sum must correspond 
to the length of the record, otherwise the appropriate error message will ap¬ 
pear. Because the record length is limited by the amount set in the FIELD 
command, it is better to use the commands LSET and RSET or MID$. 

With help from AT, numeric variables can be written into an R Data (random 
access); in this format they need not be converted into character string form. 
The parentheses must contain a pointer to the numeric variable to be saved and 
before AT the number of bytes, that should be read and saved after the address. 
Any other address can also be given, for example: 

FIELD #1,4 AT(*a%),2 AT(*b%),8 AT(*c#) 

Besides this, any combination of AS and AT is possible, for example: 

FIELD #2,4 AS a$,2 AT(*b&),8 AT(*c#),6 AS d$ 
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GET / PUT / RECORD 


GET #n [.set] 

PUT #n [.set] 

RECORD #n,set 

n.set: iexp 

GET reads a specific record from a random access data file. PUT writes a 
specific record to a random access data file. The numeric expression n (0 to 
99) is the number of the data channel that has previously been opened with 
OPEN. The optional parameter set contains a value between 1 and the number 
of records contained in the corresponding file. With no given set the next 
record will be read or written. 

Only the next record number is set for PUT or GET with RECORD. After 
RECORD #1,15 GET #1 will read record number 15 


Example: 

OPEN 'R‘,#1 ,”\private.rdm",62 

FIELD #1,24 AS name$,24 AS street$,2 AT<‘no&),12 AS dty$ 

FOR i%=1 TO 3 
INPUT ■Name : ";n$ 

INPUT "Street : -;s$ 

INPUT "No : -;no& 

INPUT -City : ";c$ 

LSET name$=n$ 

LSET street$=s$ 

LSET city$=c$ 

PUT #1,i% 

CLS 

NEXT i% 

CLOSE #1 
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GET / PUT / RECORD 


First a random access data file (mode "R") is opened with a set length of 64 
bytes. With the help of the FIELD command the record is divided into 2 fields 
of 24 bytes, one field with 4 bytes and one field with 12 bytes. The sum of the 
fields (24+24+4+12) equals 64 (the given length when the file was opened 
with the OPEN command). Finally the address data is input and set into the 
corresponding variables. This is followed by the entire record being written 
out to the file. 

OPEN ■R’,#1 ,"\private.rdm*,64 

FIELD #1,24 AS name$,24 AS street$,4 AT(*num&),12 AS city$ 

FOR i%=1 TO 3 
GET #1,i% 

PRINT "Data set number: ”;i% 

PRINT "Name : ";name$ 

PRINT "Street : ";street$ 

PRINT "NUM : ";num& 

PRINT "City : *;City$ 

NEXT i% 

CLOSE #1 

Here the random access file with the access path "PRIVATE.RDM" is opened 
in the subdirectory "ADDRESSES" and three records are read. 
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7 - Program handling 


Program handling 
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Loops 


GFA BASIC 3.0 supports an extremely large selection of loop types. Normally 
we differentiate between rejecting and non rejecting loops. Rejecting loops are 
those that checks for the break criteria before the loop is executed, while this 
criteria is checked at the end of a non-rejecting loop. The consequence is that 
non-rejecting loops are executed at least once. 

GFA BASIC recognizes two of the non-rejecting loop types, namely the FOR 
NEXT and REPEAT UNTIL loop types. A third type of standard loop type is 
the rejecting WHILE WEND loop. The fourth loop type is the DO LOOP. This 
type is actually an endless loop with no break criteria, this type of loop can be 
used with many variations in GFA BASIC. The extension WHILE or UNTIL 
can be placed behind either DO or LOOP so that special loops can be created 
that check for a logical condition at both the beginning and end of the loop. 

In each of the above named loop types additional break criteria can be built 
into the body of the loop (EXIT IF). 
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Procedures and functions 


In GFA BASIC 3.0, as with any other modem programming languages, the 
subroutines can be named. These subroutines can pass parameters; they can 
also change various variables in various calls with VAR parameter. 

Variables can be passed to subroutines as values (call by value). With the help 
of the VAR instruction the variable itself can be passed (call by reference), so 
that it can be changed by the subroutine, without having to use its global vari¬ 
able name. 

Now we come to the options of the local variable (LOCAL), that is only 
recognized in a portion of the program, this means that there is no need to 
worry about repeating a variable name within a subroutine or function. 

Using DEFFN individual functions can be defined; these can later be called 
using FN behind their names. Multiple line functions are also possible 
(FUNCTION). These are basically a special form of a procedure and return a 
parameter (through RETURN). 
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If ... ELSE ... ENDIF 


IF con [THEN] 

ELSE 

ENDIF 

con: bexp 

This commands makes it possible to make one or many commands operational 
only when a logical condition is fulfilled. The following example should 
clarify this: 

IF a=1 THEN 
PRINT ’a equals 1* 
b=2 
ENDIF 

In this case a=l is the logical condition. The commands in the lines between IF 
and ELSE are executed only if this logical condition is true. If it is FALSE 
then the program execution continues beyond the command word ENDIF. The 
command THEN is not necessary, it is enough to use the following: 


IF a=l 


instead of 
IF a=1 THEN 

The following construction is somewhat more complex: 
IF a=1 

PRINT “a equals 1" 

ELSE 

PRINT "a does not equal 1," 

PRINT "but rather “;a 
ENDIF 


7-4 


GFA-BASIC 3.0 Amiga 




If ... ELSE ... ENDIF 


In this case the commands between IF and ELSE are executed when the logi¬ 
cal condition following IF is true. Then the execution of the program continues 
after the ENDIF command. If the condition behind IF is not satisfied then the 
commands between ELSE and ENDIF are executed. This is followed by the 
execution continuing after the ENDIF. Logical true is every numerical expres¬ 
sion that does not equal 0. 

Example: 


x=1 
IF x 

PRINT "x is true" 

ENDIF 
INPUT y 

IF x=9 OR ODD(y) 

PRINT "y is an uneven number" 

ELSE 

PRINT "y is an even number" 

ENDIF 

First the text "x is true" will be displayed on the screen. Then a number will be 
asked for. Because x can not equal 9 the text "y is an un even number" will be 
displayed if you have input an uneven number and "y is an even number" will 
be displayed if y was an even number. 
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ELSE IF 


ELSE IF con 

con: bexp 

The command ELSE IF makes it possible to create a clearer IF construction. 
The following example reacts to a keypress. For S, L or I the name of a Save, 
Load, or Input routine will be called. In all other cases the text "Unknown 
command" will be displayed. The boxed version looks like this: 

DO 

t$=INKEY$ 


IF t$=“L’ 

PRINT -Load" 

ELSE 
IF t$=’S‘ 

PRINT 'Save” 

ELSE 
IF t$=T 
PRINT -Input' 

ELSE 

PRINT “Unknown Command" 
ENDIF 
ENDIF 
ENDIF 

LOOP 
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ELSE IF 


The application of ELSE IF results in a shorter listing with fewer overall in¬ 
dentations: 

OPENW 0 
DO 

t$=INKEY$ 

IF t$='L" 

PRINT "Load" 

ELSEIF t$=*S‘ 

PRINT -Save" 

ELSEIF t$=T 
PRINT -Input" 

ELSE 

PRINT "Unknown Command" 

ENDIF 

LOOP 

The creation of such a program structure follows this pattern: If the condition 
behind the IF statement is satisfied (here t$="L”), then the commands between 
IF and the next ELSE IF are executed (here PRINT "Load") and execution is 
branched to behind END IF. 

If one of the conditions behind an ELSEIF command is satisfied then all com¬ 
mands up to the next ELSE, ELSEIF or ENDIF (if no ELSE exists) are ex¬ 
ecuted and program execution branches to the command behind the ENDIF. If 
none of the conditions behind an IF or an ELSEIF are true then the commands 
between ELSE and ENDIF are executed (if there is an ELSE). 
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ON GOSUB 


ON x GOSUB proc1,proc2,... 

x: iexp 

procl, proc2: procedure name, without a parameter 

These commands branch to the xth procedure, located in the list behind 
GOSUB. Here x is a numerical expression, in which the decimal places are ig¬ 
nored (if there are any). If x is smaller then one or larger than the number of 
procedures available behind GOSUB no subroutine will be called. After a sub¬ 
routine is executed the program will resume execution at the command follow¬ 
ing the GOSUB command. 

The procedures can have no parameters passed to them with this command. 


Example: 

x=3 

ON x GOSUB procl,proc2,proc3 
x=1 

ON x+1 GOSUB procl ,proc2,proc3,proc4 

First procedure proc3 is called then procedure proc2 is called. 
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SELECT CASE 


SELECT x 

CASE y [TO z] or CASE y [,z,...] 

CASE TO y 
CASE y TO 
DEFAULT 
ENDSELECT 
CONT 

x.y.z: iexp or a string constants with a maximum of 4 characters 

The command SELECT makes the branching dependent on the value of the 
numerical expression x. The following example serves to explain this in a 
program: 

OPENW 0 
x=0 

SELECT x+2 
CASE 1 

PRINT "x equals 1” 

CASE 2 TO 4 
PRINT *x equals 2, 3 or 4" 

CASE 5,6 

PRINT "x equals 5 or 6' 

DEFAULT 

PRINT "x does not equal 1, 2, 3, 4, 5 or 6" 

ENDSELECT 

"x equals 2,3 or 4" is displayed on the monitor. First the numerical expression 
behind SELECT is evaluated, the branch condition is set (here it equals 2). 
Finally the CASE instruction goes from top to bottom checking if the current 
branch condition is found behind a CASE. In this example only 1 stands be¬ 
hind the first CASE instruction. Because the branch condition equals 2 the 
programs jumps to the next CASE. 
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SELECT CASE 


The "2 to 4" stands behind the second CASE. The condition is satisfied, when 
the branch criteria behind SELECT has a value between 2 and 4 (inclusive). In 
this case the commands between the second and third CASE are executed. 
After this the program execution branches to behind the command 
ENDSELECT. 

Another variation of the SELECT criteria is apparent behind the third CASE. 
There the chosen values are presented in a list, separated by commasif the 
current branch criteria are not to be found behind a CASE, then the commands 
between DEFAULT and ENDSELECT will be executed, as long as there is a 
DEFAULT instruction. The statement OTHERWISE can be used in the place 
of DEFAULT; it will automatically be replaced with DEFAULT by the editor. 

Numeric constants are not the only ones that can be used behind CASE, string 
variables or constants with a maximum length of four characters can also be 
given. With this, the string following CASE can have a maximum length of 4 
characters. If only one character is used the ASCII value is used as branch 
criteria. If two characters are given the value is calculated in the following 
way: 

ASCII value of the first + 255 * ASCII value of the second character. The 
input of three or four characters will continue in a corresponding pattern. 


Example: 

OPENW 0 
exit!=FALSE 
REPEAT 
key$=INKEY$ 

SELECT key$ 

CASE "a" TO -z- 

PRINT 'the lower case letter ’+key$+" was entered' 
CASE 'A' TO 'Z' 

PRINT “the upper case “+key$+‘ was entered' 

CASE 27 
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SELECT CASE 


exit!=TRUE lEnd program when with 
DEFAULT 

PRINT “Invalid toy was pmsasdr 
ENDSELECT 
UNTIL «ltl 

The key is read from within a loop and the pressed key will initiate a branch of 
the corresponding character, for example invalid input will be reported. The 
break criteria for the loop is the press of the ESC-key. 

The next example illustrates the meaning of the CONT Instruction, that only 
has an effect when it is placed in front of a CASE or DEFAULT command. 
This CONT command may not be repeated within a program that has been 
stopped and then restarted. 

Example: 

OPENW 0 
x=1 

SELECT x 
CASE 1 

PRINT "x equals 1* 

CONT 
CASE 2 

PRINT *x equals 2" 

CASE 1,3 
PRINT “x equals 3” 

DEFAULT 

PRINT “x does not equal 1,2 and 3" 

ENDSELECT 

"x equals 1" and "x equals 2 " are displayed in the window. The CONT com¬ 
mand ensures that the CASE or DEFAULT instruction behind it is jumped 
past. In this case the value behind the first CASE instruction equals the branch 
condition. Consequently the command PRINT ”x equals 1” is executed. This is 
followed by a CONT instruction which will jump past the line CASE 3 even 
though the branching condition is not fulfilled, that is it does not equal 1. This 
also ensures that the command PRINT "x equals 2 " is executed. 
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SELECT CASE 


When the next CASE or DEFAULT instruction is reached a jump to behind 
ENDSELECT will follow. This also takes place when the current branch 
criteria is found behind this CASE. 


Example: 

SELECT INKEY$ 

CASE 'a' TO 'g' 

PRINT 'a to g- 
DEFAULT 
PRINT "default" 

ENDSELECT 

When you press any of the keys a, b, c, d, e, f or g, the text "a to g", will ap¬ 
pear, with another keypress (excluding keyboard shift keys) the text "default” 
will appear. 


The various possibilities can be combined with CASE, it is therefore not 
necessary to write: 

SELECT a$ 

CASE 'a' TO "z" 

CONT 

CASE 'A' TO "Z" 

CONT 

CASE "a’,"e","i","o","u" 

PRINT "OK" 

ENDSELECT 

but the following is also correct: 

SELECT a$ 

CASE 'a' TO 'Z'.'A' TO "Z","a","e","i",... 
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FOR ... TO 


FOR l=a TO e [STEPS] 

(commands) 

NEXT I 
DOWNTO 

i: avar 

a,e,s: aexp 

The FOR NEXT loop (also called a numbered loop) serves to repeat a group of 
commands (loop body) found between the keywords FOR and NEXT. For this 
purpose the count variable n is given a beginning value of a. Now the com¬ 
mands in the body of the loop are executed until the word NEXT is encoun¬ 
tered. There the value n is increased by the value s, found behind STEP. If 
STEP is not present then n will be increased by a value of one. Now n is 
checked to be sure it has not exceeded the value i. If it has the execution jumps 
to the command following NEXT, if not execution continues with the first 
command in the body of the loop. This chain of events is continued until n is 
either larger or equal to i. 

One consequence of this is that n remains equal to the value that first exceeded 
the break criteria. The contents of the FOR loop will be executed at least once. 

Instead of using a negative STEP value s = -1 the instruction DOWNTO can 
be applied. The use of STEP is no longer possible or necessary in combination 
with DOWNTO. 

Integer variables should be used for the count variable i because they can be 
processed much faster than floating point variables. This is of course not pos¬ 
sible for steps of fractional amounts. 

Instead of typing the command word NEXT, followed by a variable (for ex¬ 
ample i%) you may type ENDFOR i%. This will be replaced with NEXT i% 
by the interpreter. 
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FOR ... TO 


Example: 

OPENW 0 
FOR i=1 TO 10 
PRINT i' 

NEXT i 

FOR i=-10 DOWNTO -1 
PRINT i- 
NEXT i 


Displays the numbers 1 2 3 4 5 6 7 8 9 10 -1 2 -3 -4 -5 -6 -7 -8 -9 -10 in the 
window. 


a$=-T*e*s*t*w*o*r*d- 
FOR j=1 TO LEN(a$) STEP 2 
PRINT MID$(a$,j,1); 

NEXT j 

The word "Testword" is displayed in the window. 
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REPEAT UNTIL 


REPEAT 

(Commands) 

UNTIL con 

con: bexp 

With REPEAT - UNTIL con, a number of commands are framed and executed 
until a logical condition con exists. When the instruction REPEAT is en¬ 
countered in a program the commands behind it up to UNTIL are executed. 
Now the logical condition behind UNTIL con is checked to see if it is true. If 
this is the case then the command behind UNTIL will be executed. If it was 
false then the program execution will jump back to the REPEAT instruction 

The commands between REPEAT and UNTIL are executed at least once as 
long as they do not contain an EXIT IF or GOTO instruction. This is not a 
conditional loop. ENDREPEAT con can be used instead of UNTIL con, and 
will be automatically replaced by the interpreter. 


Example: 

OPENW 0 
REPEAT 
UNTIL MOUSEK 

Waits for a mouse button to be pressed. 
i=l 

REPEAT 
INC i 
j=SQR(i) 

UNTIL ilO and FRAC(j)=0 
PRINT i 

The number 16 is displayed on the screen. 
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WHILE ... WEND 


WHILE con 
(Commands) 

WEND 

con: bexp 

The instructions WHILE and WEND can frame a group of commands that are 
to be executed as long as a logical condition is true. When GFA-BASIC en¬ 
counters a WHILE command it checks the logical condition that follows and if 
it is true the commands between WHILE and WEND are executed. When 
WEND is reached the program execution jumps to WHILE and the cycle is 
repeated, until con is false. ENDWHILE can be written instead of WEND and 
will be replaced by the interpreter with WEND. 


Example: 

OPENW 0 
WHILE MOUSEK=0 
PLOT MOUSEX, MOUSEY 
WEND 

Draws with the mouse until a mouse button is pressed. 
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DO LOOP 


DO 

(Commands) 

LOOP 

The command DO LOOP creates an endless loop. The program executes the 
commands between DO and LOOP and then jumps back to DO when LOOP is 
reached. 

The loop can be left during program execution only with the help of EXIT IF, 
GOTO or a program end command. Instead of the LOOP instruction ENDDO 
can also be written, it will also be replaced with LOOP by the interpreter. 


Example: 

OPENW 0 
GRAPHMODE 1 
COLOR 1,2,1 
DEFFILL 1,3,4 
DO 

MOUSE mx,my,mk 
IF mk 

PBOX mx,my,mx+25,my+25 
ENDIF 
LOOP 

When the mouse button is pressed a filled square will be drawn at the current 
mouse position. 
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DO WHILE / DO UNTIL 


DO WHILE con 
DO UNTIL con 
LOOP WHILE con 
LOOP UNTIL con 

con: bexp 

The command DO and LOOP can be modified with the addition of UNTIL 
and WHILE. The loop header DO WHILE ensures that the commands within 
the loop are only executed as long as con is true. If the loop begins with DO 
UNTIL the commands will only be executed as long as con is not satisfied. 

LOOP WHILE insures that the program branches back to DO only as long as 
con is true. For LOOP UNTIL the con must not be satisfied (FALSE) if the 
program execution is to branch back to the beginning of the loop. 

For this the conditions of DO are conditional, those of LOOP are uncondition¬ 
al . 

DO WHILE con WHILE con 

corresponds to 

LOOP WEND 

DO REPEAT 

corresponds to 

LOOP UNTIL con UNTIL con 

The command variations DO, DO WHILE and DO UNTIL can be combined 
in any combination with LOOP, LOOP WHILE and LOOP UNTIL for a total 
of nine possible loop types that can be constructed with these commands. 
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DO WHILE / DO UNTIL 


Example: 

OPENW 0 
DO 

LOOP UNTIL MOUSEK 
' waits for a mouse button to be pressed. 

DO UNTIL MOUSEK=2 
DO WHILE MOUSEK=1 
LINE O.O.MOUSEX,MOUSEY 
LOOP 

LOOP UNTIL INKEY$=’a’ 

When the left mouse button is pressed lines will be drawn, when the right 
mouse button is pressed or "a" is pressed program execution stops. 

DO UNTIL EOF(#1) 

INPUT #1.a$ 

LOOP 

Reads a sequential character string from channel one until the end of the data 
is reached. 


WHILE NOT EOF(#1) 

INPUT #1,a$ 

WEND 

Construction with WHILE WEND is slower, because an additional NOT is re¬ 
quired. 
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EXIT IF 


EXIT IF con 

con: bexp 

A loop can be branched from with EXIT IF con when the boolean con is ful¬ 
filled. The loop type is freely selectable. 

In contrast to older versions EXITIF is also possible from within IF ENDEF 
and SELECT ENDSELECT. 


Example: 

DO 

EXIT IF MOUSEK 
LOOP 
REPEAT 

EXIT IF INKEY$='x" 
UNTIL FALSE 


Ends program execution when a mouse button and then the "x" key is pressed. 
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GOSUB/PROCEDURE 


GOSUB proc [(pari,part,...)] 

PROCEDURE proc [(varl.vart,...)] 

RETURN 

proc: procedure name 

par1,par2: sexp.aexp 
var1,var2: svar.avar 

The commands of the subroutine are found between the command words 
PROCEDURE and RETURN. The name of the subroutine is found behind 
PROCEDURE and the list of variables to be passed, enclosed in parentheses, 
is found behind the name. To ensure that a GFA-BASIC command is not mis¬ 
taken for a procedure an or the word "GOSUB" is placed in front of the 
procedure name. These must be used with procedure names that are the same 
as the GFA-BASIC command (for example: @stop, @rem). 

The parameters to be passed can be constants, variables, and expressions. Vari¬ 
ables can pass their value as well as the variable itself (see VAR). 

When the program reaches the RETURN instruction then the program will 
jump to the command following the GOSUB. SUB can be used instead of the 
command word PROCEDURE, ENDPROC or ENDSUB can be used in place 
of RETURN. The interpreter will replace these internally itself. 
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GOSUB/PROCEDURE 


Example: 

OPENW 0 

GOSUB slow_printf** Manual for **”) 
@slow_print(” GFABASIC 3.0 *’) 
slow_print(’GFA-SYSTEMTECHNIK") 

PROCEDURE slow_print(t$) 

LOCAL i% 

FOR i%=1 TO LEN(t$) 

PRINT MID$(t$,i%,1); 

PAUSE 3 
NEXT i% 

PRINT 

RETURN 

a slow character output of the string. 


a=8 

@third_root(a) 

PRINT a 

PROCEDURE third_root(VAR x) 
x=x A (1/3) 

RETURN 

Calculates the third root of 8 and displays 2 on the screen. 
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LOCAL 


LOCAL varl [,var2,var3,.„] 

var1,var2,var3: avar.svar 

It is possible to limit the influence of a variable with the LOCAL command. 
The variables following LOCAL are only valid in the procedure with the 
LOCAL command as well as all procedures called from this procedure. 

Variables found in the main program (global ones), can also be listed behind 
the LOCAL command. These variables are not available to the subroutine and 
after the procedure is left will be unchanged and available to the main 
program. 


Example: 


x=2 

GOSUB test 
PRINT x,y 

PROCEDURE test 
LOCAL x.y 
x*3 
y=4 

RETURN 

The numbers 2 and 0 are displayed on the screen. 


Program handling 


7-23 




@func / FUNCTION 


@func [(par1,par2,...)] 

FUNCTION funk [(var1,var2,...)] 

RETURN exp 
ENDFUNC 

tunc: function name 

par1,par2: sexp.aexp 
var1,var2: svar.avar 
exp: sexp, aexp 

The commands of the subroutine (similar to PROCEDURE) are placed be¬ 
tween the command words FUNCTION and ENDFUNC. The name of the 
function is positioned behind FUNCTION as well as the list of variables to be 
eventually passed to the function. To call the subroutine the @ is used. This 
will be followed by a parameter list 

The parameters to be passed can be constants, variables, and expressions. Vari¬ 
ables can pass not only their values but the variable itself can be passed (see 
VAR). 

When the program execution reaches RETURN the program will jump to the 
command following the function call. If the instruction RETURN is reached 
during program execution the value determined in the function will be 
returned at the position of the function call. RETURN can be used many times 
within a function, but it is not allowed to end a function inside an IF or other 
structures without a RETURN (for example using ENDFUNC instead). 

A $ character at the end of a function name identifies functions with string 
values. 
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@func / FUNCTION 


Example: 

OPENW 0 

florida=@fak_loop( 15) 
today =@fak_recurs( 10) 


PRINT "Loop: fak(15)=';florida 
PRINT "Recursion: fak(10)=";friday 

FUNCTION fak_loop(f%) 
w=1 

FOR j%=1 TO f% 

MUL w,j% 

NEXT j% 

RETURN w 
ENDFUNC 

FUNCTION fak_recrs(f%) 

IF f%=2 
RETURN 1 
ELSE 

RETURN f%*@fak_recurs(PRED(f%)) 

ENDIF 

ENDFUNC 

The factors of 10 and 15 arc calculated within a loop and once recursively. 
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DEFFN 


DEFFN func [(x1,x2,...)]=output 
FN func [(y1,y2,..,)] 


func,x1,x2: var 

output,yl ,y2: exp 

The command DEFFN allows the definition of one line functions. The defini¬ 
tion of these functions is contained in the expression output, which can be a 
numerical as well as a string expression. The function is called with FN func 
after it has been defined. 

The variables contained in the function definition are passed as parameters. In 
the function definition the variables names xl,x2,... can be marked to be in 
output also. When the function is called the parameters y l,y2,... can be either a 
numeric or string expressions. 

When the variable xl,x2,... is also globally defined, then it cannot be accessed 
in the expression output because it contains the passing value of output. The 
variable xl,x2,... are therefore for the function local variables. 

The instruction FN can also be replaced by an @. Functions can be enclosed 
as desired, but with DEFFN they cannot be recursive (break not possible). 
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DEFFN 


Example: 

OPENW 0 

DEFFN test(y,a$)=x-y+lEN(a$) 
x=2 

PRINT @test(4,"abcdef*) 

The numbers 4 (24+6) are displayed on the screen. 

DEFFN firstJast$(a$)=LEFT$(a$)+RIGHT$(a$) 
b$=@first_last$CTEST') 

PRINT b$ 

The text "TT" appears on the screen. 

DEFFN power_four(x)=x A 4 
DEFFN fourth_root(x)=x A {1/4) 

PRINT @fourth_root(@power_four(1024)) 

The number 1024 is displayed on the screen. 
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ON BREAK 


ON BREAK 
ON BREAK CONT 
ON BREAK GOSUB proc 

proc: procedure name 

These three commands determine the reaction to be taken when the control, 
shift (left only) and alternate keys are pressed simultaneously. When this key 
combination is pressed the program will usually be stopped; it can however 
serve to branch to a specific procedure. For this purpose ON BREAK GOSUB 
sets the procedure proc to be branched to. 

With ON BREAK CONT the pressing of the named key combination turns the 
normal reaction off. ON BREAK turns the normal reaction (program break) on 
again. 

Example: 

ON BREAK GOSUB test 

PRINT 'Press the CONTROL, SHIFT (left) and ALTERNATE keys' 

DO 

LOOP 

PROCEDURE test 
PRINT 'That was it* 

ON BREAK 
RETURN 

The opportunity to press the key combination is created. If it is pressed, the 
normal Break routine is turned on. 
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ON ERROR 


ON ERROR 

ON ERROR GOSUB proc 
RESUME [NEXT] 

RESUME [mar] 

proc: procedure name 
label: label name 

The occurrence of an error normally leads to an error message and a program 
break. With ON ERROR GOSUB it is possible to branch execution to the pro¬ 
cedure proc. In this procedure the reaction to the error can be set. With the 
command ON ERROR the normal error handling is returned to normal, there¬ 
fore the output of an error message and a program break will occur. 

When an error is encountered an ON ERROR Command will be executed. In 
order to make it possible to react to many succeeding errors the command ON 
ERROR GOSUB proc must be contained in the error handling routine. 

The RESUME command permits a special reaction to an error. It is only 
meaningful in the error handling routine. With RESUME NEXT the program 
execution will continue with the command following the error. RESUME label 
ensures that the program will continue execution at the marked label. The 
command RESUME with NEXT or a label will jump to the command where 
the error was encountered and continue. If this is a fatal error (see FATAL), 
then only the command RESUME label can be used, not the command 
RESUME NEXT or RESUME with no label. 
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ON ERROR 


Example: 

ON ERROR GOSUB error_routine 
ERROR 5 

PRINT ‘and again ...* 

ERROR 5 

PRINT *was not reached" 

PROCEDURE error_routine 
PRINT ‘Ok, Error handling." 

RESUME NEXT 
RETURN 

The text "Ok, error handling." and "and again ..." are displayed on the 
screen; then the error message for ERROR 5 is displayed on the screen 
"square roots are only for positive numbers". The mark for RESUME may be 
found in a procedure as well as in the main program. 
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ERROR/ERR 


ERROR X 

ERR 

ERR$(x) 

x: aexp 

With ERROR the error with the number x is executed (see appendix for error 
handling table). This can be used to test error handling routines. The variable 
ERR contains the number of the encountered error. With it, specific reactions 
to errors can be developed. 

The function ERRS returns the string the GFA-BASIC Error message with the 
number x. 


Example: 

ON ERROR GOSUB errorJiandling 
INPUT "Which error would you like: ",e 
ERROR e 

PROCEDURE errorjiandling 
PRINT "that was Error No.: *;ERR 
RETURN 

Asks the user for an error number and displays this number. 
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EVERY / AFTER 


EVERY ticks GOSUBproc 

EVERY STOP 

EVERY CONT 

AFTER ticks GOSUB proc 

AFTER STOP 

AFTER CONT 

ticks: iexp 

proc: procedure name 

With the help of the commands EVERY and AFTER procedures can be ex¬ 
ecuted after a specific time. The command EVERY ensures that the-procedure 
proc is executed every ticks time unit; AFTER ensures that the procedure is 
executed once after ticks time units. 

The time units are given in two hundredths of a second (ticks=200 is therefore 
one second). Time resolution amounts to about one tenth of a second, while 
during mouse movements it is somewhat higher. 

With the help of EVERY STOP the branching to a procedure after a specific 
time has elapsed is turned off, with EVERY CONT it is turned on once again. 
The command AFTER STOP and AFTER CONT perform the opposite. 

Commands are only checked to ensure they function properly, if a command 
that is very slow is executed, such as INPUT, QSORT, data operations or 
similar, it could make the execution of above time commands inaccurate. 
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EVERY/AFTER 


Example: 

OPENW 0 

EVERY 4 GOSUB lines 
line!=TRUE 
GRAPHMODE 3 
DEFFILL 1.0 

PLOT MOUSEX,MOUSEY 
REPEAT 
IF MOUSEK=1 
EVERY STOP 
ELSE 

EVERY CONT 
ENDIF 

DRAW TO MOUSEX,MOUSEY 
UNTIL MOUSEK=2 

PROCEDURE lines 
INC y% 

LINE 160,y%,320,y% 

IF y%=200 
y%=0 
ENDIF 
RETURN 


Lets lines run from the top to the bottom in the upper right half of the screen 
while at the same time drawing with the mouse is possible. Pressing the left 
mouse button turns the moving line on and off. The program can be stopped 
with the right mouse button. 
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EVERY / AFTER 


PRINT 'The text will follow in 3 seconds' 

PRINT 'if you press no keys.' 

AFTER 600 GOSUB text 
REPEAT 

UNTIL INKEY$” OR ENDIT! 

AFTER STOP 

PROCEDURE text 
PRINT 

PRINT 'Here is the Text" 
endit!=TRUE 
RETURN 

Three seconds after the start of the program a text will appear if no keys have 
been pressed. If a key is pressed the program is ended. 
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REM 


REM x 
’x 

ccommand !lne>! x 

x: any text 

Any text can be put onto a line that begins with REM or ’. This text has no ef¬ 
fect on the program and its syntax is not checked by the editor. Instead of ’ any 
similar character can be also used, but during input it is automatically replaced 
by The advantage to using other characters is that they may happen to be 
within easy reach during typing. 

In addition to this any comment can be placed behind a command on the same 
line as long as it is preceded by an exclamation mark(!). This symbol is not al¬ 
lowed with DATA Instructions. 


Example: 

REM comment 
' PRINT "Comment” 

PRINT "REM" I Comment 

The word REM is displayed on the screen. 
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GOTO 


GOTO label 

label: a programmer defined label 

With the help of a label, positions within a program can be set to allow branch¬ 
ing with the command GOTO. The program execution is then branched to the 
position of the label. The label can be made up of letters, numbers, under¬ 
scores, and points. It may also, in contrast to variable names, begin with a 
number, it must however end with a colon. When branching to a label with 
GOTO, the colon is not included in the name. 

It is not possible to branch out of or into procedures or functions with the 
GOTO command. GOTO commands usually make programs unreadable very 
quickly and should only be used when absolutely necessary. 


Example: 

OPENW 0 
PRINT "Position 1" 

GOTO jump_mark 
PRINT "Position 2" 
jump_mark: 

PRINT "Position 3" 

The text "Position 1" and "Position 3" are displayed on the screen. 
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PAUSE / DELAY 


PAUSE x 
DELAY x 

x: aexp 

The command PAUSE halts the program execution for x/50 seconds. DELAY 
has the same effect, the execution of the program is delayed for x 
seconds(theoretically resolution is in milliseconds). 

"x" can also be a floating point number, but in that case you must bear in 
mind that the maximum timer resolution is 1/50 of a second. Smaller values 
would therefore default to this amount, i.e. the wait would last 1/50 of a 
second. Moreover you must bare in mind that because Amiga operating system 
is multitasking other interruptions may occur. DELAY therefore waits for a 
minimum of 1 second. 


Example: 

PRINT "Start” 

PAUSE 100 
PRINT "a pause" 

DELAY 2 
PRINT "End" 

The text "Start" and two seconds later "a pause" appear on the screen, then two 
additional seconds later "End" appears. 
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END / EDIT / STOP 


END 

EDIT 

STOP 

These commands serve to end the program, The command END stops the 
program execution and displays an alert box with the text Program end. After 
the selection of the proper alternative GFA-BASIC 3.0 returns to the editor. 

EDIT ends the program execution and returns directly to the editor. STOP dis¬ 
plays an alert box with the alternatives STOP and CONT. When CONT is 
chosen, program execution will continue. When STOP is chosen GFA-BASIC 
will go to the direct mode. There the value of variables can be changed or 
viewed and the program can be continued with the CONT command. 

To end the program without returning to the editor you must use QUIT or 
SYSTEM. 


Example: 


x=3 
STOP 
PRINT x 

Select the "STOP” button when the corresponding alert-box appears. Now 
enter the following command in direct mode: 

PRINT x 

The number 3 will be displayed on the screen. Enter now: 


x=4 

CONT 

The last command of the listing (PRINT x) is now processed. The number 4 is 
displayed on the screen, that is the value entered in direct mode. 
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NEW 


NEW 

This instruction erases a program. In direct mode a prompt will be displayed. 
In the Editor this command is available through Shift-F4 or mouse click (with 
prompt). 

This command can also be used from within a program. In this way a program 
can be written that will initialize a standard working environment At the end 
of the initialization program the command NEW insures that this program is 
deleted. 
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LOAD 


LOAD f$ 

f$: sexp 

The command LOAD serves to load a GFA-BASIC-Program. The string ex¬ 
pression f$ contains the access path to the desired data file. Without an exten¬ 
sion the default .GFA will be used. 

Example: 

LOAD "DFO:TEST.GFA" 

Loads the program data named TEST.GFA from the main directory DFO. 
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SAVE / PSAVE 


SAVE f$ 

PSAVE f$ 

f$: sexp 

The command SAVE saves program data under the name f$. With PSAVE the 
file is saved with list protection (that is the data will be directly run the next 
time it is loaded with LOAD, it will no longer be possible to list this program). 
With no extension the default .GFA will be used. 


Example: 

SAVE "A:\TEXT.GFA" 

Saves the current program data under the name TEST.GFA on drive DFO. 
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LIST / LUST 


LIST [f$] 

LLIST [f$] 

f$: sexp 

The command LIST shows the current program listing on the screen. An op¬ 
tional access path can be given, under which the program data can be saved in 
ASCII format Program data, that is later to be merged into another program 
must be saved with LIST or SAVE.A (from the editor menu list) in ASCII for¬ 
mat 

With no extension given the default extension .LST will be used. With LLIST 
the current program can be output to the printer. 

The printer listing can only be stopped by turning the printer off. After this it 
takes about 30 seconds until the program is executed further or the editor is 
returned to. (LLIST is similar to the point commands in the editor section). It 
is also possible to reroute the output (just like with OPEN). 


Example: 

LIST “DF1 MEST.LST” 

Saves the current program under the name ..."TEST.LST" in ASCII format to 
drive DF1. 

.1170 
.pi 66 
LLIST 

Prints the current program with a line length of 70 characters and 66 lines to a 
page to the printer. 
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_ CHAIN 

CHAIN f$ 

f$: sexp 

The command CHAIN makes it possible to load and execute a GFA-BASIC 
program. With no extension given the default extension .GFA will be used. 

Example: 

CHAIN "DFOiEXTRA.GFA" 

Loads and executes the program EXTRA.GFA. 
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RUN 


RUN [f$] 

f$: sexp 

The command RUN executes the current program. If an additional complete 
data name is given then the corresponding program will be loaded and started. 

Example: 

RUN -DF0:PART_2.GFA- 

Loads and executes the program named PART_2.GFA from drive DFO. 
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SYSTEM / QUIT 


SYSTEM [ n ] 

QUIT [ n ] 

n: iexp 

The commands SYSTEM and QUIT have the same effect They end the 
program and exit GFA-BASIC. Upon leaving the interpreter the calling 
program (usually CLI) will be passed a variable. The normal convention is to 
pass zero to indicate that no error has occurred. 
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TRON/TROFF 


TRON 
TRON #n 
TROFF 

n: iexp 

The command TRON (trace on) ensures that every executed command is listed 
to the screen. This list can also be sent to a file through a channel number. The 
command TROFF turns this function off. 


Example: 

PRINT -Start:" 

TRON 

FOR i%=1 TO 5 
PRINT i% 

NEXT i% 

TROFF 
PRINT -End - 

The word "Start:" is displayed. The numbers 1 to 5 and the command used to 
accomplish this are then displayed. After this the word "End" is displayed. 
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TRON/TROFF 


OPENW 0 

OPEN "0",#1 ,'tron,lsf 
TRON #1 
FOR i%=1 TO 10 
PRINT i% 

NEXT i% 

TROFF 
CLOSE #1 

OPEN -0-,#2,'pm:- 
TRON #2 

FOR i%=10 TO 630 STEP 10 
LINE i%,0,i%, 100 
NEXT i% 

TROFF 
CLOSE #2 

The numbers 1 to 10 are displayed as well as the appropriate commands and a 
row of vertical lines 10 pixels apart This output is to the screen as well as to 
the printer. 
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TRON/TRACE 


TRON proc 
TRACE$ 

proc: procedure name 

Using the TRON proc command a procedure, that will execute before every 
command, can be specified. The variable TRACES contains the command that 
is to be executed next The application of TRON proc in connection with 
TRACES makes for a very efficient error search. For example, in connection 
with the next command to be executed, the output of specific variables can be 
sent to the printer to help follow the variable value through all the changes. 

It is important that the TRON procedure interferes as little as possible. Do not 
use PRINT commands in screen masks (TEXT). 


Example: 

OPENW 0 
TRON tr_proc 
GRPHMODE 3 
DO UNTIL MOUSEK 
Xl%=100+RAND(200) 
y1%=100+RAND(100) 

X2%=200+RAND(200) 

Y2%=200+RAND(100) 

PBOX x 1%,y 1 %.x2%,y2% 

LOOP 

PROCEDURE tr_proc 
PRINT AT(1,5) SPACE$(80) 

PRINT AT(1,5) LEFT$(TRACE$,79) 

PAUSE 20 
RETURN 

This program draws randomly divided rectangles on the screen. Pressing the 
control key displays on the screen the command that is being executed at that 
moment. The program is ended by pressing a mouse button. 
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$ 


$text 

text: any characters 

The command $, which is handled as a REM by the interpreter, is used for 
control of the compiler. You can find an exact description of this command in 
the GFA-BASIC 3.0 Compiler handbook (when available). 
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INLINE 


INLINE adr.num 

adr: 4 byte integer variable, no array variables 

num: integer constant smaller than 32700 

Remarks are not allowed directly behind this command because the area nor¬ 
mally used for a remark is the exact location that the desired memory location 
is reserved at. Initially the memory area is erased (filled with zeros). This 
memory area always begins at an even address. When INLINE is executed the 
address of this integer variable is written to adr. When the program is saved or 
loaded this memory area is saved or loaded with the program. 

If the cursor is positioned at the line containing the INLINE command and the 
help key is pressed a menu line will appear in the upper most line of the editor 
with the entries LOAD, SAVE and CLEAR. It is possible to load or save data 
in the line containing the INLINE command with the "LOAD" or "SAVE" op¬ 
tion. The extension .INL is used in this process. The menu point "CLEAR” is 
used to erase the reserved memory area. Pictures or assembler programs can 
be loaded into this memory area. The command DUMP will create a hex dump 
on the printer. 
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C:adr([x,y,...]) 


adr:avar (at least 32 Bit, adr% is better) 
x,y: iexp 

The function C calls a C or Assembler subroutine that can be found at the ad¬ 
dress adr. The parameters x,y„.. can be passed in brackets. The parameters can 
be either 32-bit-long words or 16-bit-words, 16-bit-word length is the default. 
Long words can be passed when a L: precedes the parameter. When this func¬ 
tion is called, the return address is placed on the stack and the parameter set. 
For example: 

VOID C:adr%(L:x,W:y,z) 

creates the following on stack: 

(sp)-» return address 
4(sp) -» x (4 bytes) 

8(sp) —* y (2 bytes) 

10(sp) -♦ z (2 bytes) 

The value that is returned when the subroutine is branched out of is the value 
contained in the register dO, (this must be followed by an RTS). 


Example: 

The Assembly program supplied here fills a memory area (for example an in¬ 
teger array) with numbers (long words) from 0 to n beginning with a specific 


address. 




206F0004 

move.l 

4(sp),a0 

;beginning address 

202F0008 

move.l 

8(sp),d0 

;number of values 

7200 

moveq.l 

#0,d1 

;counter 

6004 

bra.s 

connecticut_2 

;jump in loop 

20C1 

connecticut_1 :move.l 

dl ,(A0)+ 

;k>op, write values 

5281 

addq.l 

#1,d1 

;increment counter 
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B081 connecticut_2:cmp.l dl.dO 
64F8 bcc.s connecticuM 

4E75 rts 

The BASIC program is as follows: 

FOR i%=1 TO 11 
READ a% 

asm$=asm$+MKI$(a%) 

NEXT i% 

DATA 

$206F.$0004,$202F ,$0008, $7200, $6004, $20C1 ,$5281 ,$B081 ,$64F8 
$4E75 

DIM x%(10000) 
asm$=V:asm$ 

-C :asm%(L :V :x%(0), L:10000) 

PRINT "for example: x%(12): -;x%(12) 

Fills the array x%0 with the numbers 0 to 10000. With this application the ex¬ 
ecution of the C: functions corresponds to: 

FOR i%=1 TO n% 
x%(i%)=i% 

NEXT i% 

Another option is to use the INLINE command to insert an assembly program 
into a GFA-BASIC 3.0 program. First create a file that contains the above as¬ 
sembly program (for example after the above READ-DATA loop), using: 

BSAVE “COU NT.IN L", V:asm$,22 

Then input the following program: 

INLINE asm%,22 
DIM x%(10000) 

~C:asm$(L:V:x%(0),L:10000) 

Then press the help key in the line containing the INLINE command, select 
load and load the file COUNT.INL. Now this program can be saved with Save. 


;no, continue 
;retum to GFA-BASIC 
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MONITOR 


MONITOR [x] 

x: iexp 

This command serves to call assembly subroutines, debug programs, or other 
utility programs. For this purpose the Illegal instruction vector (address 16) 
must be rerouted to the address of the subroutine. The MONITOR command 
creates an illegal instruction exception that branches to a subroutine. This sub¬ 
routine must end with RTE (RETURN from Exception). The parameter x is a 
parameter that must be written to register dO. One applications example is a 
program used as a debugger (as with C:). For this GFA-BASIC is loaded and 
started from the debugger. Then enter the command MONITOR asm% directly 
after the INLINE command. After the program starts the debugger will be ini¬ 
tialized through the "Illegal Instruction". Now the area in dO can be either dis¬ 
assembled or edited. Finally, the execution of the BASIC program can be 
repeated with the GO command of the debugger. 

CAUTION: 

Before using this command you must make sure that a machine language 
monitor has initialized the monitor vector. GFA-BASIC cannot set this vector 
before the jump to its address because it does not know where the monitor is. 
If the monitor is not at the current vector address this results in the program or 
system crash (Guru meditation 4). 
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CALL 


CALL adr([x,y,...]) 

adriexp 
x.y: iexp 

With the help of the CALL command assembly subroutines can be called. 
Parameter adr is the address where the assembly program is to be found It is 
possible to pass a parameter list. After the CALL command is initiated all the 
return addresses will be found on stack (the assembly routine must end with 
RTS). This is followed by the number of parameters to be passed in 16 bit 
values and finally the address after which the parameters can be found in 
memory as 32 bit values. All parameters are treated as long words (32 bit). 

It is possible to pass strings as well; in this case the parameter passed is the ad¬ 
dress of the string. 

Stack: 

(sp) -» RETURN address 
4{sp) -> parameter number (16 bit) 

6(sp) -> parameter array address (32 bit) 
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RCALL 


RCALL adr,reg%() 

reg%0:4-byte integer array name 
adr: iexp 

The command RCALL makes it possible to set the values of registers before 
an assembly routine is called and to read the contents of the registers after the 
routine has been executed. The array reg%0 is used for this purpose, this is in 
elements of 4-byte-integer-types and has at least 16 elements. Before the start 
of the assembly routine the address of this array must be copied to the register 
in the corresponding array element. The following applies (with OPTION 
BASE 0): 

Data register dO through d7 in reg%(0) through reg%(7) 

Address register aO through a6 in reg%(8) through reg%(14) 

User-Stack-Pointer (a7) inreg%(15) (only return) 

Example: 

DIM r%(15) 

r%(14)=JntBase 

r%(8)=0 

RCALL JntBase,r%() 

This program calls the operating system routine DisplayBeep and correspond¬ 
ing ~DisplayBeep(0). 
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8 - Graphics 



SETCOLOR 


SETCOLOR register,red,green,blue 
SETCOLOR register,mix 
COLOR color 

register,red,green,blue,mix.color: iexp 

The first variation of SETCOLOR sets the proportion of the color components 
red, green and blue in a specific color register. With this the intensity of the 
color is set on a scale from 0 (low) to 15 (high). The number of available 
colors depends on the current resolution of the screen. In the second variation 
the color is set with the following formula: mix=red * 512 + green * 16 + blue, 
where the values for red, green, and blue are in the range 0 to 15. The 
hexadecimal representation is much more appropriate here (SETCOLOR 
l,&hF00 (=light red)). 

Because each open screen has its own color palette both of these commands 
are only applicable to the current screen. The command COLOR determines 
the character color. Here the expressions front, back and out will have one of 
the screen resolution dependent values between 0 and 63. 

The character color of the foreground is set in front and the background color 
in back. The background color is only presented in GRAPHMODE 1 (JAM2). 
The expression out contains the color value for the framing of the fill com¬ 
mand (PBOX, PCIRCLE, PELLIPSE, POLYFILL). 


Example: 

OPENS 1,0,0,640,200,2,32 
SETCOLOR 0.0 

Opens a screen and sets the color to black in color register 0. 
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DEFFILL 


DEFFILL [color], [style], [pattern] 

DEFFILL [color], bitpattern$ 

color,style,pattern: iexp 
bitpattem$: sexp 

This command sets the fill pattern for the commands PBOX, PCIRCLE, PEL- 
LEPSE, POLYFILL, and FELL. It sets the color, style, and pattern of the filling 
and makes it possible to define the pattern. For the variable color the values 
from 0 to 63 can be used depending on the resolution (see the overview at the 
beginning of this chapter). The following applies for style: 

0 = empty 

1 = filled 

2 = dotted 

3 = hatched 

Twenty-four point-patterns, or 12 line-patterns can be selected using pattern 
(see the appendix: pattern table). 

In the second command variation the bit information for the definition of the 
fill pattern is passed in the variable bitpattemS and must be in word format. 

The string length automatically sets the fill pattern height. This height is al¬ 
ways a power of 2 (1, 2, 4, 8...), while the length is twice as wide (2, 4, 8, 
16,...) where the fill patterns are 16 bits wide. For multi color fill patterns a 
dummy area is added to the string so that the fill pattern is given in con¬ 
catenated levels (for 4 bitplanes and 16 bits high: 4*(16*2)=128 characters + 
1). The maximum string length is 257. 

The parameters found in front can be omitted by replacing them with a 
comma. For example, DEFFILL ,2,4 selects the fill pattern 2,4 and leaves the 
fill color unchanged. 
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DEFFILL 


Example: 

OPENW 0 
GRAPHMODE 1 
DO 

COLOR RAND(64),RAND(64),RAND(64) 

DEFFILL 1 ,RAND(2)+2,RAND(24)+1 

PBOX RAND(320),RAND{256),RAND(320),RAND(256) 

LOOP 

Draws various sized rectangles with randomly selected fill patterns in the win¬ 
dow. 

FOR i=1 TO 16 

f$=f$+MKI$(RAND(65535)) 

NEXT i 
DEFFILL 1,f$ 

PBOX 100,100,150,150 

Draws a box with randomly generated fill patterns. 
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BOUNDARY 


BOUNDARY n 

n: iexp 

The instruction BOUNDARY turns the automatic framing of the fill area on or 
off. If n equals zero the framing is turned off and for non zero n it is turned on. 


Example: 

DEFFILL 1,2,2 

BOUNDARY 1 framing is turned on 

PBOX 50,50,100,100 

BOUNDARY 0 (framing is turned off 

PBOX 150,50,200,100 

Draws a filled square with and without framing. 
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DEFLINE 


DEFLINE def 

def:iexp 

The command DEFLINE determines how lines, those drawn with the com¬ 
mands LINE, BOX, CIRCLE, ELLIPSE and POLYLINE, will appear. 

A16 bit value that sets the appearance of the line is set in "def". One set bit in 
the definition corresponds to a point In drawing mode GRAPHMODE 1 those 
pints not set are presented in the background color. 

When "def’ is set to a value in range 0 to 6, the following standard patterns are 
used: 

0 Lines in background color 

1 Cross hatched lines 

2 Lines close together 

3 Dotted lines 

4 Dashed lines 

5 Lines wide apart 

6 The line pattern: dash, dot, dot.. 


Example: 

OPENW 0 

DEFLINE &X1111000011110000 
COLOR 1,2 
GRAPHMODE 1 
LINE 20,20,200,100 

Draws a two-colored line in the window. 
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GRAPHMODE 


GRAPHMODE n 

n: iexp 

The command GRAPHMODE sets the way the graphic outputs are to be com¬ 
bined with each other. The numeric expression n stands for 4 possible modes: 

0 JAM1 replace 

1 JAM2 transparent 

2 COMPLEMENT xor 

4 INVERSID reverse transparent 


If n has a value of 0, (default) the new pattern will be ORed with the previous 
pattern. When n equals 1 the new pattern replaces the previous pattern. When 
n=2 each pixel that was not previously set is set, and each pixel that was pre¬ 
viously set is erased (the pattern is therefore inverted XOR combination). 

In mode 4 the new pattern is first inverted and then ORed with the new pat¬ 
tern. The combinations are also possible, so 6=INVERSVID+COMPLEMENT 


Example: 

OPENW 0 
COLOR 1,0,1 
FOR i%=1 TO 8 
GRAPHMODE i%-1 
DEFFILL 1,2,18+i% 

PBOX 75*i%-50,20,75*i%,70 
DEFFILL 1,3,i% 

PBOX (75*i%)-70,50,75*i%-20,100 
NEXT i% 

The example shows 8 pairs of squares with various patterns combined in the 
four modes. 
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RASTPORT 


RASTPORT adr 

adriexp 

Rastport are the drawing levels of the screens, windows and alert boxes. With 
the command RASTPORT the current work rastport can be set. If the rastpport 
address "adr" is set then all graphic output will be to this rastport until either a 
new rastport is set or the value 0 is set in "adr". 

If a new screen is opened the address of the screen can be determined with the 
function SCREEN(index). Now the rastport address of the screen can be deter¬ 
mined with the function PEEK 0 and the offset within the structure to be read. 

Please note that no clipping takes place with the output to a screen rastport, the 
programmer is responsible for this himself. 


Example: 

RASTPORT SCREEN( 1)+84 
OPENW 2 

RASTPORT {WINDOW(2)+50} 

The rastport of the opened screen is first set as the current rastport. Please note 
the offsets 84 and 50 which specify the position of rastport pointers and win¬ 
dow structure within the screen. 


NOTE: Without proper set-up, this will crash the system. 
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CLIP 


CLIP x,y,w,h [OFFSET xO.yO) 

CLIP xl.yl TO x2,y2 [OFFSET xO.yO] 

CLIP #n[OFFSET xO.yO] 

CUP OFFSET x,y 
CLIP OFF 

x.y.h ,xO,yO,x,y 1 ,x2,y2,n: iexp 

This group of instructions is used for clipping. This is a limiting of graphic 
output to any rectangular screen section. To set these screen sections (clipping 
rectangles) the coordinates of the diagonally opposite comers, as well as the 
width and height, must be given. 

There are various variations of the CLIP-command. CLIP x,y,w,h makes it 
possible to specify the left x coordinate as "x", the upper y coordinate as ”y”, 
as well as the width "w" and the height "h" of the limiting rectangle. 

Another possibility is the command CLIP xl.yl, TO x2,y2. Here the coor¬ 
dinates of the diagonally opposite comer points (xl.yl) and x2,y2) are passed. 

The third variation makes it possible to limit the output to the size of the win¬ 
dow "n". With the named variations the optional command set OFFSET xO,yO 
it is possible to set the origin to the point with the coordinates xO,yO. Addition¬ 
ally the command OFFSET xO,yO can stand alone which will have the same 
effect and the graphic output will be set to the point (xO.yO). The clipping is 
turned off using the command CLIP OFF. The limiting of the graphic output 
does not apply to the commands GET, PUT. 
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PLOT / LINE / DRAW 


PLOT x,y 
LINE Xl,y1,x2,y2 
DRAW [TO] [x,y] 

DRAW [xl.yl] [TO x2,y2] [TO x3,y3] [TO ...] 

x,y,x1,y1,x2,y2: iexp 

PLOT draws a point with the coordinates x,y on the screen. LINE draws a line 
between the coordinates xl,yl and x2,y2. Style and color of these lines can be 
set with DEFLINE and COLOR. 

DRAW x,y corresponds to the command PLOT. With DRAW TO x,y a line is 
drawn from the coordinates x,y and the last point set. It doesn’t matter if the 
point was set with PLOT, LINE or DRAW. Another variation of the DRAW 
command is DRAW xl.yl TO x2,y2. This corresponds to the line command. 
Additional coordinates can be added making it possible to draw polygons. 
Finally the last variation or the DRAW Command makes it possible to input 
commands, similar to the specific graphic commands from the LOGO (Turtle 
Graphic) programming language, and the standard plotter language HPGL 
from Hewlett Packard. With this it is possible to simulate a plotter on the 
screen. 
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PLOT / LINE / DRAW 


Example: 

PENW 0 

x=50 

y=50 

color=POINT(x,2*y) 

PRINT color 
PLOT x,2*50 
LINE 10,10,200,100 
PRINT POINT(x.lOO) 

Draws a point and determines the character color. 

DO 

MOUSE mx,my,mk 
IF mk=1 

DRAW TO mx,my 
ENDIF 

EXIT IF mk=2 
LOOP 

When the left mouse button is pressed, a line is drawn between the current 
mouse coordinates mx,my and the last point to be set. The loop is left follow¬ 
ing a press of the right mouse button. 
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DRAW / SETDRAW 


DRAW expression 
DRAW(i) 

SETDRAW 

i: iexp 

expression: a series of sexp and iexp, the first must be sexp, 
separated by a comma, semicolon or apostrophe. 

With DRAW an imaginary marker will be moved over the screen and is able to 
draw. This closely resembles the programming language LOGO. The 
parameters of the individual commands are floating decimal point, they can 
also be given in strings. The commands are: 


FDn Forward 
BKn Backward 
SXx Scale X 
SYy Scale Y 


LTw Left turn 

RT w Right turn 
TT w Turn to 


moves the Pen n Pixels forward 

moves the Pen n Pixels backward 

scales the Pen movement for FD and BK 

with the given scaling factor. SX and SY work on n only 

with the commands FD and BK. The scaling is turned off 

with SXO or SYO (faster then the scaling with factor 1 

(SX1.SY1)). 

gives the angle w around which the drawing direction is 
to turn to the left 
opposite to the right 

returns the current angle "w" for the following assign¬ 
ments: 


0 ° 

t 

270° «— zero point —* 90° 

l 

180° 


the input for w=angle is in degrees. 


MA x,y Move absolute moves the Pen to the absolute coordinates x and y 
DA x,y Draw absolute moves the Pen to the absolute coordinates x and y 

and draws a line in the current color from the last 
Position to the point (x,y) 
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DRAW / SETDRAW 


MR xr,yr Move relative like MA, however moves to the last position 
DR xr,yr Draw relative like DR, however moves to the last position. An 

abbreviation for the expression DRAW 
"MA”,x,y,"TT",w is in the command SETDRAW 
x.y.w. 

CO c COLOR sets the color c as the drawing color. 

PU PEN UP raises the marker. 

PD PEN DOWN lowers the marker. 

Additionally the following inquiry functions are available. 

DRAW(0) returns x-position (as fdp, value) 

DRAW(l) returns y-position (as fdp, value) 

DRAW(2) returns angle in degrees (as fdp, value) 

DRAW(3) returns scaling of the x-axes (as fdp, value) 

DRAW(4) returns scaling of the y-axes (as fdp, value) 

DRAW (5) returns Penflag (i-=PD, 0=PU) 

Example: 

OPENW 0 

DRAW "ma 160,200,tt0" 

FOR i&=3 to 10 
corner(i%,90) 

NEXT i& 

PROCEDURE comer(n&, r&) ! n-number of comers, r=edge length LOCAL i& 
FOR i&=1 TO n& 

DRAW Td",r&,“rt',360/n& 

NEXT i& 

RETURN 

Draws a polygon. 

FOR i=0 To 359 STEP 8 
SETDRAW 160,100,i 
GRAHMODE 3 

DRAW Id 45 rt 90 fd 45 rt 90 fd 45 rt 90 fd 45" 

DRAW ’bk 90 rt 90 bk 90 rt 90 bk 90 rt 90 bk 90" 

GRAPHMODE 1 


Istart at 160, 200 with 0 angle, 
'draw a polygon with i corners. 


Graphics 


8-13 




DRAW / SETDRAW 


DRAW Id 45 rt 90 fd 45 rt 90 fd 45 rt 90 fd 45" 

DRAW "bk 90 rt 90 bk 90 rt 90 bk 90 rt 90 bk 90" 

NEXT i 

Draws a small and a large rectangle; they turn about their individual axes. 


1%=48 

• diamond 1 

DRAW "ma60,100 tt45" 

DRAW fd-,1%," rt90 fd",l%." rt90 fd',1%," rt90 fd*,l%," rt 90" 

' small rhomboid 
DRAW "mr 100,0 tt45" 

DRAW "sx0.5 syO" 

DRAW fd-,1%."1190 fd",l%,* rt90 fd",l%," rt90 »d",l%," rt90" 

' wide rhomboid 
DRAW "mrlOO.O tt45" 

DRAW "sxO sy0.5" 

DRAW "fd-,1%," rt90 fd',1%,- rt90 fd',1%,- (190 fd',1%,' rt90' 

‘ wide and tall rhomboid 
DRAW -mrlOO.O tt45' 

DRAW "sx3 sy2" 

DRAW "fd",l%," rt90 fd",l%," rt90 fd",l%," xt90 fd"J%," rt90" 

Draws three rhomboids and a diamond. A diamond is used as the output object 
and the other figures are created by changing the x and y scaling. 
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BOX/PBOX 


BOX Xl,y1,x2,y2 
PBOX x1,y1,x2,y2 

x1,y1,x2,y2:iexp 

BOX draws a square with the diagonal opposite coordinates xl,yl and x2,y2. 
PBOX draws a filled square. 

Example: 

OPENW 0 

BOX 20,20.120,120 

x=150 

DEFFILL 1,2,4 
PBOX 20,20+x,120,120+x 

Draws a filled rectangle and a non-filled rectangle. 
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CIRCLE / ELLIPSE 


CIRCLE x,y,r 
PCIRCLE x,y,r 
ELLIPSE x,y,rx,ry 
PELLIPSE x,y,rx,ry 

x,y,r,w1,w2:iexp 

CIRCLE draws a circle around the middle point with the coordinates x,y and 
the radius r. PCIRCLE draws a filled circle. 

ELLIPSE draws an ellipse with the middle point coordinates x,y and the 
horizontal radius r. PELLIPSE draws a filled ellipse or ellipse segment. 


Example: 

OPENW 0 
CIRCLE 160,100,100 
ELLIPSE 160,100,50,100 
PCIRCLE 160,100,50 
PELLIPSE 160,100,100,50 

Draws a few circles and ellipses. 
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POLYLINE 


POLYLINE n.xo.yo [OFFSET x_off,y_offl 
POLYFILL n,x(),yO [OFFSET x_off,y_off] 

n,x_off,y_off: iexp 
x(),y(): avar Array 

POLYLINE draws a line object with n comers. The x,y coordinates of the 
comer points are in the arrays x() and yO, The first comer point is x(0) and 
y(0), the last in x(n-l) and y(n-l). The first and the last are automatically con¬ 
nected. Additionally a level (x_off) or a perpendicular (y_off) OFFSET can be 
added to these coordinates. 

POLYFILL fills the polygon with a pattern and color; they can be set with 
DEFFILL. 


Example: 

OPENW 0 
GRAPHMODE 1 
DIM x%(30),y%(30) 

DO 

COLOR RAND(64),RAND(64),RAND(64) 
DEFFILL 1 ,RAND(4),RAND(25) 

FOR i%=0 TO 30 
x%(i%)=RAND(320) 
y%(i%)=RAND(200) 

NEXT i% 

POLYFILL 30,x%(),y%() 

LOOP 


Draws random filled polygons with 30 comers. 
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POINT 


POINT(x.y) 

x,y: iexp 

The color of the point with the coordinates x,y is determined and the variable 
is returned. Here values from 0 to 63 are possible depending on the screen 
resolution. 


Example: 

OPENW 0 
a=POINT(100,100) 

PLOT 100,100 
b=POINT(100,100) 

PRINT a,b 

Writes the color of the screen coordinate 100,100 before and after the PLOT 
command to the screen. 
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FILL 


FILL x,y[,c] 

x,y,c: iexp 

This command fills any shape area. The fill begins at the coordinate x,y. When 
c is included the fill is limited to points of the color c and the edge of the 
screen. 

Without c or with c=-l every point is given another color then the start point 
(x,y). 


Example: 

OPENW 0 
LINE 0,180,639,180 
FOR i=1 TO 19 
BOX i*20,100,i*20+20-i, 180 
TEXT i*20-4,195,i 
DEFFILL ,2,i 
FILL i*20+1,101 
NEXT i 

Draws a straight line on which rectangles of various patterns place themselves 
without regard for the destruction of the pattern. 

LINE 0,180,639,180 
FOR i=1 TO 19 
BOX i*20,200,i*20+20-i,180 
TEXT i*20-4,195,i 
DEFFILL ,2,i 
FILL i*20+1,101,1 
NEXT i 

Draws a straight line with various rectangles placed on top of each other with 
regard to the color limits. This way the pattern remains intact. 
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CLS 


CLS [#n] 

n: iexp 

Erases the screen by using <ESCxExCR>. Can also be rerouted to a file. 

This commands deletes only the text area of a window. It is, therefore, possible 
that the complete window will not be erased. A small area of the window to 
the right or below can still retain the graphic elements. In such a case it may be 
better to use the command CLEARW. 


Example: 

OPENWO 

PBOX 100,100.500,200 

REPEAT 
UNTIL MOUSEK 
CLS 

Fills part of the screen with a square and then erases it after a mouse button is 
pressed. 


8-20 


GFA-BASIC 3.0 Amiga 


TEXT 


TEXT x,y,expression 

x,y,l: iexp 

expression: sexp or aexp 

Displays the character string s$ as graphic text at the coordinates x,y. This 
point is located at the left comer of the first character of the string s$. 

Example: 

OPENW 1 
DO 

TEXT MOUSEX, MOUSEY,i% 

INC i% 

LOOP 

Writes a graphic text in various variations on the screen. 
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GET/PUT 


GET x1,y1,x2,y2 l section$ 

PUT xl,yl,sections [.mode,mask] 

x1,y1,x2,y2,mode: iexp 
section$: svar 

The command GET puts a rastport section (32768 bytes) into a string variable. 
The variable xl and yl set the start coordinates, and x2 or y2 set the end coor¬ 
dinates of the graphic section. In contrast PUT draws a rastport section saved 
with GET at the points x,y in the current window, "mode" determines how the 
section is to be combined in bit pattern with the window contents. 

Normally the window contents are copied with no changes with a value of 192 
(&HC0) for "mode". In the following table the most important combination 
rules are listed: 

Mode Combination rule 

30 The target bit pattern is replaced by the source bit pattern. 

50 The target bit pattern is inverted. 

60 Exclusive OR combination of the source and target it pattern. 

80 Only the source and target bits with the identical pattern are set. 

CO The source pattern is copied to the target area. 

The individual bits of the parameter "mask" determine the bit planes. 
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VSYNC 


VSYNC 

This command serves to synchronize the screen construction (that is, the 
program waits for a vertical blank interrupt of the viewport of the current 
screen). VSYNC can be used for the animation of screen sections with GET 
and PUT commands. 


Example: 

OPENW 0 
t%=TIMER 
FOR i%=1 TO 100 
VSYNC 
next i% 

PRINT SUB(TIMER,t%)/200 

Prints the time required for 100 screen cycles. 
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DISPLAY 


DISPLAY ON 
DISPLAY OFF 

With the commands DISPLAY ON and DISPLAY OFF, the DMA bit of a play 
field is set or erased. In this manner it is possible to draw on a play field and 
then display the drawing upon its completion. Before the drawing is begun the 
DMA bit must be erased with DISPLAY OFF and after the drawing is com¬ 
plete set with DISPLAY ON. 
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9 - Event-, menu-, screen- and 
window handling 


Event-, menu-, screen- and window handling 
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Event handling 


There are specific commands in GFA-BASIC that make it possible to access 
intuition messages easily. The management of these events is accomplished 
through ON MENU xxx GOSUB, xxx is the event that is to be reacted to. 

This activity is monitored by using the ON MENU xxx GOSUB command in 
which xxx is the event on which an action shall be taken. Every time this com¬ 
mand is called it checks to see if one of these events has taken place. If an 
event that needs action has occurred, the program will branch to the specified 
procedure. 
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Pull down menus 


Specific commands used for the management of pull down menus in GFA- 
BASIC 3.0 are discussed in this section. Unfortunately there is much con¬ 
fusion in the literature on this subject. Therefore the concepts used in this 
handbook must first be discussed. We will use the idea of pull down menus as 
the main concept. The menu list, that part of the menu that is always visible, 
can be found in the upper line of the screen. This line contains the individual 
menu titles. If the mouse arrow touches one of these menu titles, the pull down 
menu will appear. Each entry in this menu, that can be individually chosen, is 
called a menu entry. Menu entries can display additional menus when they are 
selected with the mouse arrow. These special menus are named sub menus, 
their entries correspond to the sub entries. 

This concept is not common, but rather it applies to this handbook only; in 
many books another definition is used. 

When a pull down menu is created these entries are stored in a string array 
m$(). With the command MENU m$0 this pull down menu is placed on the 
screen. The command ON MENU GOSUB defines the procedure to be called 
when the corresponding menu entry is selected. 

During program execution a check to see if an entry has been selected is made 
every time an ON MENU command is encountered. 

The command MENU KILL turns off the pull down menu. The command 
MENU(x,y) makes it possible to replace menu entries with a broken line or in 
light text, this will also make the menu entry non selectable. 
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MENU 


MENU m$() 

m$(): String array 

This command is used to create pull down menus which are supported by the 
commands of the previous section (ON MENU, MENUO). 

MENU m$0 presents the pull down menu on the screen. The menu titles and 
entries are contained in the character string m$(). The following format must 
be used for the organization of the array m$(): 

1. title of the menu. 

2. list of menu entries. 

3. empty string, to mark the end of the menu. 

An additional empty string follows the empty string of the final menu to mark 
the end of the entire pull down menu. A menu entry preceded by a minus sign 
will automatically be presented in light text and will not be selectable. If the 
menu entry begins with an exclamation mark then a sub entry will be created. 
If the sub entries are followed by additional entries with an exclamation mark 
these will be treated as sub entries of the first sub entry. 
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MENU (x) 

x: aexp between 0 and 11 inclusive 


MENU () 


The variable MENU(O) to MENU(ll) contain all relevant data needed to 
manage events. The construction of the MENU array is similar to the construc¬ 
tion of the IntuiMessage structure of the operating system. 


MENU(0) Menu string array index of the BASIC Menu 

MENU(l) Class corresponds to IDCMP Flags 

MENU(2) Code depending on the message 

encountered, menu number for example. 
MENU(3) Qualifier contains information after a 

special key has been pressed. 

MENU(4) IAdress address of gadgets or other objects. 

MENU(5) MouseX X-coordinates of the mouse relative to the 

upper left comer of the current window. 
MENU(6) MouseY Y-coordinates of the mouse relative to the 

upper left comer of the current window. 
MENU(7) Seconds Seconds and Micros contain the system 
MENU(9) Micros time since the event 
MENU(IO) Windowaddr. address of the window in which 


the message was encountered. 


Exit point of the following explanation is MENU(l). In MENU(l) the iden¬ 
tification number (IDCMP) of the event encountered can be found. The other 
elements of the message buffer contain information depending on the contents 
of MENU(l). The following table will explain this information. 


The value of MENU(l) is given followed by the meaning of this value and 
finally the variable in which important information about this value can be 
found. 
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MENU () 


MENU (1)=1 

The size gadget of a window has been pressed. 
MENU( 10): The address of the window. 

MENU(1)=2 

The size of a window has been changed. 

MENU(10): The address of the window. 

MENU(1)=4 

The contents of a window must be redrawn. 

MENU( 10): The address of the window. 

MENU(1)=8 

A mouse button has been pressed or released. 

MENU(2): =104 left mouse button pressed 
=232 left mouse button released 
=105 right mouse button pressed 
=233 right mouse button released 

MENU(1)=16 

The mouse is being moved. 

MENU(5): X-coordinates of the mouse. 
MENU(6): Y-coordinates of the mouse. 

MENU(1)=32 

A gadget has been pressed. 

MENU(4): Address of the gadget. 

MENU(1)=64 

A gadget has been released. 

MENU(4): address of the gadget. 

MENU(1)=128 

A requester is displayed in a window. 

MENU( 10): address of the window. 


9-6 


GFA-BASIC 3.0 Amiga 




MENU () 


MENU(1)=256 

The menu button of the mouse has been pressed for menu selection. 
MENU(2): selected menu (bitfield). 

The key to the bit field is as follows: 
Menu-number=MENU(2)AND31 
Menu-entry=SHR((MENU(2),5)AND63 
Sub-entry=SHR((MENU(2), 11 )AND31 
With BASIC menus MENU(O) contains the index of the selected 
menu point within the suing array. 

MENU(1)=512 

The close field of a window has been pressed. 

MENU( 10): address of the window. 

MENU(1)=1024 

A key has been pressed or released. 

MENU(2): Scan code of the key. (see scan codes in the appendix) 

MENU(1)=2048 

The window is not ready to display a requester. 

MENU(IO): address of the window. 

MENU(1)=4096 

If the last requester of the window has been closed. 

MENU(10): address of the window. 

MENU(1)=8192 

The window is not ready to display a menu list. 

MENU(10): address of the window. 

MENU(1)=16384 

The system preferences are being changed. 

MENU(1)=32768 
A disk has been placed in a drive. 
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MENU () 


MENU(1)=65536 

A disk has been removed from a drive. 

MENU(1)=131072 

A change has been made on the work bench. 

MENU(1)=262144 

The window is activated with the mouse. 

MENU(IO): address of the window. 

MENU(1)=524288 

The window is deactivated. 

MENU( 10): address of the window. 

MENU(1)=1048576 

The mouse is being moved. 

MENU(5): Delta X-coordinates 
MENU(6): Delta Y-coordinates 

MENU(1)=2097152 
A key has been pressed. 

MENU(2): ASCII code of the key depending on the set key map. 

MENU(1)=4194303 

Timer report (every 1/10 second) 

The values for MENU(7) through MENU(10) are always set independent of 
the message. 
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ON MENU 


ON MENU t 
SLEEP 

t: iexp 

The command ON MENU watches for the occurrence of an event. The proce¬ 
dure that is to be branched to should be set before this command is executed. 
The commands that can be set are described in the rest of this chapter. To con¬ 
stantly watch over these events, it is necessary to repeat this command con¬ 
tinuously. Therefore the ON MENU command is usually placed in a loop. 

The parameter t contains the time (in Intui-ticks=tenths of a second) after 
which the ON MENU command will be ended. 

SLEEP is equivalent to ON MENU 1 and waits for one Intui-tick or some 
other event (for example menu selection). Intui-ticks (Intuition timer events) 
are generated only by active windows. 
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ON MENU ... GOSUB 


ON MENU GOSUB proc 
ON MENU KEY GOSUB proc 
ON MENU BUTTON GOSUB proc 
ON MESSAGE GOSUB proc 

proc: name of a procedure 

When a message is encountered the program will branch to the procedure with 
the name "proc”. The observation is accomplished with every ON MENU or 
SLEEP command. The construction of the message structure was described in 
the section about MENU(x). The message that can be encountered is depend¬ 
ent on the IDCMP flag of the window set with OPENW. Therefore if the 
parameters of the OPENW command set the IDCMP flag to MENUPICK, the 
program would branch to "proc" after a menu message was encountered. 

With ON MENU GOSUB proc a procedure will be set and after a menu selec¬ 
tion has been made this procedure will be branched to. The menu selection can 
be determined within this procedure with the help of MENU(0). 

With ON MENU KEY GOSUB proc a procedure is assigned to handling of 
keyboard input, with key code in MENU(2). 

With ON MENU BUTTON GOSUB proc a procedure is assigned to handling 
of mouse buttons. MENU(2) contains an indication of a button press or 
release. 


Example: 

DIM a$(100) Iread menu 

DO 

READ a$(i%) 

EXIT IF a$(i%)=— 

INC i% 

LOOP 

a$(i%)=" 

DATA main, about, info, test, 

DATA file, load, save, -, oops, 

DATA * 

OPENW 2,0,10,640,120,&H408.1 IRawKey and Buttons 
MENU a$() 
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ON MENU... GOSUB 


MENU 3," TEST - Ichange text for entry 3 

MENU KEY 6.65 lAmiga-A for Load 

ON MENU GOSUB men '.assign routines 

ON MESSAGE GOSUB msg 

ON MENU BUTTON GOSUB but 

ON MENU KEY GOSUB key 

DO 

LOOP Iwait LOOP 

PROCEDURE men (menu selection 

PRINT MENU(0),a$(MENU(0)) 

RETURN 

PROCEDURE msg lany message 

PRINT "msg:" 

FOR i%=0 to 9 
PRINT HEX$(MENU(i%),8) 

NEXT i% 

PRINT 

RETURN 

PROCEDURE but Imouse buttons 

PRINT "but:" 

SELECT MENU(2) 

CASE &H68 

PRINT "left mouse button pressed' 

CASE &HE8 

PRINT "left mouse button released" 

CASE &H69 Inot as a result of menu 

PRINT ‘right mouse button pressed" 

CASE &HE9 Inot as a result of menu 

PRINT "right mouse button released" 

ENDSELECT 

RETURN 

PROCEDURE key IRawKey (see appendix) 

PRINT "key:"'HEX$(BCLR(MENU(2),7),2)' 

IF BTST(MENU{2),7) 

PRINT "released" 

ELSE 

PRINT "pressed" 

ENDIF 

RETURN 

Events are waited for and from those events only those having to do with the 
mouse are acted upon. The program can be ended by pressing the right mouse 
button. 
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MENU KILL/MENU X, Y 


MENU KILL 
MENU x,y 
MENU x,str$ 

MENU KEY x,y 

x,y: aexp 
str$: sexp 

MENU KILL turns the pull down menu off. Additionally MENU KILL turns 
the ON MENU GOSUB settings off. With the command MENU x,y the x-th 
entry of a BASIC menu can be changed. The number of the entry corresponds 
to the string index of the array, in which the pull down menu entry is found. 
The numbering begins with zero; titles and empty strings are counted. 

The second parameter y determines what is to be done with the x-th menu 
entry. The following options are available: 

y effect 

64 Menu entry is displayed in inverse if selected. 

128 A box is drawn around the menu. 

192 The menu should be un-changeable. 

256 Set check mark before entry. 

New text can be assigned for a menu entry using str$. The new string should 
not be longer than the old one, all excess characters will be ignored. 

The command MENU KEY assigns an ASCII character (shortcut) to a menu 
entry. When this character is pressed together with the right Amiga key it in¬ 
vokes the assigned menu entry, "x" is the index of the entry and "y" is the 
ASCII value of the key. When "y" is zero the assignment is deleted. In the 
menu a shortcut is represented with an Amiga symbol and the ASCII value of 
the key. 
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MENU KILL / MENU X, Y 


Example program for the pull down menu section: 

DIM entry$(22) 
i%=-1 
REPEAT 
INC i% 

READ entry$(i%) 

UNTIL entry$(i%-1)="Last Item* 

entry$(i%)=" 

entry$(i%+1)=“ 

OPENW 0 

MENU entry$0 

ON MENU GOSUB menu_evaluate 
DATA Desk, Test, 

DATA File, Load, Save,-, Quit, 

DATA Title, Entry 1, Entry 2, 

DATA Last Item 
REPEAT 
ON MENU 
UNTIL MOUSEK=3 
PROCEDURE menu_evaluate 

’ MENU(0) contains the array index of the chosen menu entry 
m%=MENU(0) 

PRINT entry$(m%) 

ALERT 0,"Check Mark in front?",l,"YeslNo",a% 

IF a%=l 

MENU m%,257!set check mark 
ELSE 

MENU m%,64! invert 
ENDEF 

ALERT 0,"Light Text?l(NOT selectable)",l,”YeslNo'>% 

IF a%=l 
MENU m%,16 
ELSE 

MENU m%,64 
ENDIF 
RETURN 
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Creates and manages a pull down menu. When a menu entry is clicked on, the 
text of the entry is displayed on the monitor and a prompt as to how the menu 
entry is to be presented appears. Press both mouse buttons to exit. 


9-14 


GFA-BASIC 3.0 Amiga 



Screen Commands 


All graphic resolutions of the Amiga are accessible through the very comfort¬ 
able screen commands of GFA-BASIC. GFA-BASIC contains the commands 
OPENS, CLOSES, MOVES, FRONTS, BACKS and TITLES as well as the 
function SCREEN- with all possible screen options. 

Screens serve as basis for all graphic output There are virtual screens, that can 
have various resolutions independent of each other. 

When opening a screen, indices from 1 to 31 are used making screen handling 
very simple. The index 0 is set aside for the workbench screen. If no screen is 
opened then all output will be directed to the workbench screen. Only the 
commands FRONTS and BACKS are available with the workbench screen. 

The number of screens, that can be opened at any one time, is limited only by 
the indices and graphic memory.The memory required for each screen is de¬ 
pendent on the size and bit plane depth of each screen. A screen with one bit 
depth requires less memory then a screen with five bit depths. Caution must be 
taken to ensure that a screen with fewer bit planes can handle the minimum 
number of required colors. 

The maximum size of a screen is 1024 pixels in width and height. A width of 
640 pixels and a height of 512 can be displayed on the Amiga monitor, begin¬ 
ning with the upper left comer of the screen. 

The following resolution can be set for Screens: 

HIRES 32768 (&H8000) 

In HIRES mode a maximum of four bit planes are allowed. The visible area is 
640 pixels wide and 256 pixels high. The number of colors that can be 
presented is determined by the number of the bit planes. Here 2 A number of bit 
planes is used. 

A maximum of 16 different colors are allowed in the HIRES mode. 
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Screen Commands 


LACE 4(&H4) 

A special mode is turned on in LACE mode doubling the number of lines 
presented. Every picture is made up of two half pictures .Because the monitor 
works with a frequency of 50 hz and a complete picture takes 1/30 of a second 
to complete the screen will flicker somewhat. The visible width and height is 
320 * 512 pixels. With 5 bit planes 32 different colors are possible in this 
mode. 

The LACE mode can be combined with the HIRES (32772(&H8004)) mode 
which will additionally double the horizontal resolution. Because the HIRES 
mode only supports 4 bit planes this combination can only support 4 bit 
planes. 

EXTRA HALF WIDTH 128(&H80) 

With a maximum of 320*256 visible pixels in this mode six bitplanes and a 
maximum of 64 different colors can be displayed. 

HAM 2048(&1I800) 

In this special resolution mode it is possible to display 4096 colors simul¬ 
taneously. This is possible through a trick, because the computer recognizes 
2 A 6 bitplanes=64 colors. Hold and Modify (HAM) means, take one pixel and 
modify it with the pixel color of the previous pixel. 

This resolution mode only makes sense if at least five bit planes were opened 
in the OPENS command. If we draw in the color of the first sixteen color 
registers (0-15) no visible change from the other resolutions will be noticed. 

Only when the color registers 16-63 are used will a difference in the modes be 
noticed. 

If the combination of the bits from bit plane five and six equals %00 then the 
colors will not be changed. This is the case when the colors of the color 
registers 0-15 are used. 
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Screen Commands 


If the bit combination corresponds to %0, %10 or %11 then the color of the 
undetermined pixel to the left will be copied and changed. Here the bit com¬ 
bination from bit plane 1-4 is taken and the four color bits are set, without 
changing the corresponding color register. 

The following applies: 

%01 = set blue bits 
%10 = set red bits 
%11 = set green bits 

In combination with the resolution mode these additional settings can be 
made: 

GENLOCK VIDEO 2(&H2) 

Using a Genlock Video Interface the screen background color can be replaced 
with the video picture. 

SPRITES 16384(&H4000) 

If hardware sprites are to be created this flag must be set. 
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OPENS 


OPENS nr [,x,y,w,h,bitp,mod] 

nr,x,y,w.h,bitp: aexp 
mod: iexp 

The command OPENS opens a screen. 

The index number, from 1-31, can be given n "nr". The index number 0 stands 
for the workbench screen. If no additional parameters follow the index then a 
standard screen will be opened. The screen size, bit plane depth and resolution 
are then set to the default values. 

If the command OPENS is executed several times with the same screen index 
the screen will become the current output screen. Changes in parameters will 
be seen if the screen is first closed with CLOSES. 

x and y contain the start coordinates of the screen. Setting x (distance from the 
left side of the screen) is not used when a screen is opened but simply included 
for future operating systems. 

The values for the width w and the height h are relative to the upper left comer 
of the screen. If x, y, w or h are negative values an error message will be dis¬ 
played. 

The description of the resolution modes has already been presented. The 
values that can be given to "mod” are as follows: 


Value 

Name 

Visible area 

Bit Planes 

32768 

HIRES 

640x200 

4 

32772 

HIRES LACE 

640x400 

4 

2048 

HAM 

320x200 

6 

128 

EXTRA_HALF_WIDE 

320x200 

6 

4 

LACE 

320x400 

5 

0 

STANDARD 

320x200 

5 
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OPENS 


The number of bit planes that are to be set for the screen are found in "bitp". 
The number of bit planes in the table means the maximum number that can be 
set. 


Example: 

OPENS 1,0,0,320,256,6,4H800 lopen screen in HAM mode OPENW 0,0,0.320,256,0, 
0 

GRAPHMODE 0 
FOR r4=0 TO 15 
FOR g4=0 TO 15 
FOR b4=0 TO 15 
x4=r4*20 
y4=g4+(b4*16) 

COLOR r4+4H30 
LINE x4,y4,x4+19,y4 
INC x4 

COLOR g4+4H20 
LINE x4,y4,x4+19,y4 
INC x4 

COLOR b4+4H10 
LINE x4,y4,x4+19,y4 
NEXT b4 
NEXT g4 
NEXT r4 

A screen is opened in HAM mode and a HAM color palette is displayed. 


Event-, menu-, screen- and window handling 


9-19 



CLOSES 


CLOSES no 

no: aexp 

The command CLOSES closes an opened screen and returns the memory area 
of the screen, "no" is the index of the screen. If the screen with the index "no" 
does not exist an error message will be returned. CLOSES closes all opened 
windows on the screen before the screen is closed. 


Example: 

OPENS 1 

i%«1 

DO 

MOVES 1.0.1% 

INC i% 

EXIT IF i%=200 
LOOP 

A screen is opened, moved and closed. 
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FRONTS / BACKS 


FRONTS no 
BACKS no 

no: aexp 

Every opened screen contains two gadgets on the upper right edge. It is pos¬ 
sible to change the screen through these gadgets. If one of these gadgets is 
clicked on with the mouse the screen will be displayed in the foreground or 
hidden in the background. The same can be accomplished with the command 
FRONTS and BACKS. FRONTS shows the screen with index "no" in the 
foreground. BACKS moves the screen to the background. 


Example: 

FOR i%=1 To 5 

OPENS i%,0,i%*30.320,200,1,128 
NEXT i% 

DO 

FRONTS RAND{5) 

BACKS RAND(5) 

LOOP 

Five screens are qpened at various positions and an endless loop moves the 
screens from the foreground to the background. 
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MOVES 


MOVES no,x,y 

nr,x,y: aexp 

The position that the screen is to be drawn is given in x and y in the command 
OPENS. With the command MOVES the position can be changed. In contrast 
to the operating system function MoveScreenO x and y are given in absolute 
coordinates. The coordinates are based at the upper left comer of the screen. 
Please notice that the values x and y may never become negative because an 
error message will the appear. 

If a window is displayed on the screen during a MOVES command the mouse 
pointer can not be moved. If a window is moved within a moved screen, errors 
in the operating system will occur. 


Example: 

OPENS 1 
OPENS 2 
OPENW 0 
FRONTS 1 
FOR x&=0 TO 2 
FOR i&=0 TO 100 
MOVES x&,0,i& 

NEXT i& 

NEXT x& 

Two windows are opened and moved. 
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TITLES 


TITLES no,str 

no: aexp 
str: sexp 

Each screen can have a title on the uppermost line. If a screen is opened with 
only the index then the previous title will be used for the screen. 

With the command TITLES the title of the screen can be changed after it has 
been opened. The character string given in "str" is entered into the screen with 
the index "no". If "str" contains an empty string then the previous title will be 
erased. 


Example: 

OPENS 1 
a$=’NEW TITLE" 

TITLES 1.a$ 

The screen contains a new title after it is opened. 
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SETSPEN 


SETSPEN detall_pen,block_pen 

detail_pen,block_pen: iexp 

Both of these commands can be used to initialize screens. They replace the 
previously initialized values. "detail_pen" sets the color number of the color 
that the screen title is to appear in. "block_pen" sets the color number of the 
screen title field. 
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SCREEN 


SCREEN(no) 

SCREEN(adr) 

no.adr: iexp 

The function SCREEN returns the address of the screen when the screen index 
"no" is given or the screen index when the screen address "adr" is given. 


Example: 

OPENS 1 
adr%=SCREEN(1) 
index%=screen(adr%) 
print adr%,index% 

The first SCREEN function determines the address, which is used to return the 
screen index in the second screen function. 
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Window Commands 


Windows are screen areas that can be enlarged, shrunk and moved depending 
on their type. GFA-BASIC handles the commands OPENW, CLOSEW, 
CLEARW, TITLEW, FULLW, MOVEW, SIZEW, LIMITW, FRONTW, 
BACKW as well as WINDOWO making for very comfortable window 
management. 

Graphic and text output can normally only take place in the current window or 
rastporL If the interpreter encounters a command that calls for screen output 
and no window has yet been opened or RASTPORT command executed then a 
window will automatically be opened with the index 0 on the current screen. 

Indices for windows are in range 0 to 31. 
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OPENW 


OPENW no 

OPENW no[,x,y,w,h,IDCMP,flags] 

OPENW no[,x,y,w,h,IDCMP,flags,scrno] 

OPENW no[,x,y,w,h,IDCMP > flags,scrno l bltmap] 

CLOSEW no 

no,x,y,w,h,scmo,IDCMP,bitmap:iexp 

OPENW opens the window index "no". If no additional parameters are given a 
standard window will be opened. Window 0 covers the whole screen with the 
exception of the title line, while windows 1 through 15 occupy a quarter of the 
screen. #1 lies in the upper left comer, #2 in the upper right comer, #3 in the 
lower left comer, #4 in the lower right comer and #5 through #15 are centered. 

"x” and "y” contain the jump coordinates relative to the upper left comer of the 
screen, "w" and "h" contain the width and height of the window. Negative 
values or values outside the screen area create an error message. 

IDCMP means, "Intuition Direct Communications Message Port". Each win¬ 
dow has a message port, through which events can be captured, as soon as the 
window is activated. What message is to be acted upon can be specified 
through the IDCMP. If the IDCMP value for MOUSEBUTTONS is set the 
message port will always be advised when a mouse button is pressed with the 
value of MOUSEBUTTON. It is very easy to select the messages in a program 
and react to them. 
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OPENW 


The following events can be captured: 

1 (&H1) SIZEVERIFY 

The size gadget has been clicked on. This is especially important if output, that 
must be ended before a window size is changed, is to be placed in a window. 

2 (&H2) NEWSIZE 

If the window size is changed the message NEWSIZE will be returned. 

4 (&H4) REFRESHWINDOW 

The window contents must be redrawn. Refresh window applies only to win¬ 
dows in which the SMART_REFRESH or SIMPLE_REFRESH has been set. 

8 (&H8) MOUSEBUTTONS 

A mouse button has been clicked. This applies only to the right mouse button 
because the right mouse button turns on the menu list If RMBTRAP-flag in 
the window is set the menu list can no longer be turned on and a message will 
still be returned after the mouse button is pressed. 

16 (&H10) MOUSEMOVE 

If the REPORTMOUSE flag in the window flag is set this message will be 
sent as soon as the mouse is moved. 

32 (&H20) GADGETDOWN 

When a gadget is selected with the mouse. This does not apply to the standard 
window gadgets. 

64 (&H40) GADGETUP 

A gadget is released. This does not apply to the standard window gadgets. 
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OPENW 


128 (&H80) REQSET 

The first requester in the window is opened. 

4096 (&H1000) REQCLEAR 

The last requester in the window is erased. 

256 (&H100) MENUPICK 

The right mouse button is released for menu selection. 

512 (&H200) CLOSEW1NDOW 

The close field of the window has been clicked. 

1024 (&H400) RAWKEY 

A key has been pressed. The normal key codes arc determined. 

2097152 (&H200000) VANILLAKEY 

A key has been pressed. The ASCII code depending on the key map settings is 
returned. 

262144 (&H40000) ACTIVEWINDOW 
Activation of the window. 

524288 (&H80000) INACTIVEWINDOW 
Inactivation of the window. 

1048576 (&H100000) DELTAMOVE 

Deltamove is used in combination with IDCMP Mousemove. If the mouse is 
moved the mouse position relative to the start position are determined. 

4194303 (&H400000) INTUITICKS 
Every 1/10 second a message is sent. 

16384 (&H4000) NEWPREFS 
The system preferences are changed. 
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OPEMW 


32768 (&H8000) DISKINSERTED 
When a new disk is put in the drive. 

65536(&H10000) DISKREMOVED 
When a disk is removed from the drive. 

The last three messages are only received when the window is not active. The 
entries given in "flags" determine the appearance of the window. The follow¬ 
ing values can be used with flags: 

1(&H1) WIN DO WSIZING 

System gadget for enlarging or shrinking the window. 

16(&H10) SIZEBRIGHT 

The gadget is placed on the right side of the window. 

32(&H20) SIZEBOTTOM 

The gadget is placed on the lower edge of the window, (full 80characters) 

2(&H2) WINDOWDRAG 
The window can be moved. 

4(&H4) WINDOWDEPTH 

The window can be clicked into the fore- or background. 

8(&H8) WINDOWCLOSE 
System gadget to close the window. 

0(&H0) SMARTFRESH 

The visible window contents are copied into a memory area. If the window is 
covered by other windows the window contents can be replaced, not however 
when the size of the window is changed. 
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OPENW 


64 (&H40)S1MPLERFRESH 

If the window contents must be replaced the message Refreshwindow will be 
passed to the message port. 

128 (&H80) SUPERBITMAP 

A bitmap which contains the window contents of each window is used. When 
the window size is increased the contents of the window do not need to be 
replaced. The initialization of the bitmap must be accomplished by the 
programmer himself. 

131072 (&H20000)NOCAREREFRESH 
The message to refresh the window is not sent. 

256 (&H100) BACKDROP 

The window can not be placed in front of others. 

512 (&H200) REPORTMOUSE 
The mouse position is determined. 

1024 (&H400) GIMMEZEROZERO 

The edge component and the window contents are saved separately so that 
drawing can not exceed the window edge. The drawing coordinates are rela¬ 
tive to the upper left edge of the window area. 

2048 (&H800) BORDERLESS 
No edge component is drawn. 

4096 (&H1000) ACTIVE 

The window is activated when it is opened. 
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OPENW 


65536 (&H10000) PMBTRAP 

The message MOUSEBUTTONS should be determined for the right mouse 
button, "scmo" contains the screen index of the screen on which the window is 
to be displayed. If OPENW is executed without these parameters the window 
will be opened at the current screen. You should make sure that "scmo" points 
to a screen that is presently opened otherwise an error message will be 
returned. 

If a window is to be created whose contents are to be saved in their own bit¬ 
map, "bitmap" must contain the address of the bitmap. If SUPERBITMAP is 
set in the window flags "flags" then an individual bitmap for redrawing the 
window contents must be set. The bit map must be at least the size of the win¬ 
dow. 

The command CLOSEW closes the window with the index no. If the window 
with the index number no is already closed an error message will appear. 


Example: 

OPENS 1 
OPENS 2 
OPENW 0 

OPENW 1,0,0.100.200.1,15 
OPENW 2,0,0,100,200,0,15.1 

Two screens and three windows are opened. The first two windows are on the 
last screen opened and the last opened window is on the first opened screen. 
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CLEARW / TITLEW / BACKW / FULLW 


CLEARW no 
TITLEW no,a$[,b$] 

FRONTW no 
BACKW no 
FULLW no 

no: iexp 

a$,b$: sexp 

The command CLEARW erases the contents of the window with the index 
"no". TITLEW writes the text a$ in the upper line of the window with the 
index "no". If b$ is given it will be displayed in the title line when the window 
is active. FRONTW gets window index "no" and places it in the foreground. 
BACKW pushes the window to the background. FULLW enlarges the window 
index "no" to full screen size. 


Example: 

DEFFILL 1.2,4 
PBOX 0,0,639,399 
OPENW 1 
PAUSE 60 
FULLW 1 

PRINT ’Window 1’ 

OPENW 4,0,0,100,100,0.&HF 

PAUSE 50 

CLEARW 1 

OPENW 3 

PAUSE 50 

FRONTW 1 

PAUSE 50 

CLOSEW 1 

TITLEW 4,’Window 4’ 

PAUSE 100 

CLOSEW 3 

CLOSEW 4 

CLOSEW 0 


A window appears, is changed and disappears once again. 
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MOVEW / SIZEW / LIMITW 


MOVEW no.x.y 
SIZEW no,w,h 

LIMITW no,mln_x,mln_y,max_x,max_y 

no,x,y,w,h,min_x,min_y,rnax_x,max_y: aexp 

MOVEW moves the window with the index "no" to the absolute x and y posi¬ 
tion relative to the upper left comer of the screen. The window index "no" can 
be enlarged or shrunk with the SIZEW command, w and h contain the new 
width and height of the window. LIMITW sets the minimum and maximum 
size of a window. min_x and min_y contain the minimum size of the window 
and max_x and max_y contain the maximum size of the window. This applies 
to changing the window size with the mouse as well as with the command 
SIZEW. 

Example: 

OPENS 1 
OPENS 2 

OPENW 0,0.0,160.100,0,15,1 
OPENW 1,0,0,160,100.0,15,2 
LIMITW 0,100,100,200,200 
FULLW 0 
FULLW 1 

A window is displayed on a screen and with the command FULLW brought to 
it’s maximum size on the screen. 
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SETWPEN 


SETWPEN detail_pen,block_pen 

detail_pen,block_pen: iexp 

SETWPEN works like the corresponding screen commands. In detail_pen the 
color number the window title is to appear in is set. block_pen sets the color 
number of the window title field. 
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WINDOW 


WINDOW(nr) 

WINDOW(adr) 

nr.adr: iexp 

The function WINDOW returns the window index "no" or the address of the 
window structure and, vice versa, when the address "adr” is given the index 
will be returned. 


Example: 

OPENW 1 
adr%=WINDOW(1) 
index%=WINDOW(adr%) 

PRINT adr%,index% 

The first WINDOW function determines the address and the second the index 
of the window. 
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ALERT 


ALERT sym,text$, default,button$, choice 

sym, default: iexp 
text$,button$: sexp 
choice: avar 

The ALERT command places an alert requester on the screen. The expression 
sym is for later versions of GFA BASIC and does not apply to this version. 

The text that is to appear in the Alert Box is contained in the string expression 
text$. Four lines with a maximum of 40 characters each are allowed. The lines 
are separated with a I character. Lines that are longer than 40 characters are cut 
off. 

The expression default sets the default mouse button that will be highlighted in 
the alert box. This button can be selected by simply pressing return or enter, it 
can also be selected with the mouse button. If no button with the default num¬ 
ber exists then the alert box cannot be left simply with the return or enter key, 
it must be left using a mouse button. 

The string expression button$ contains the text of the gadget The maximum 
text length per gadget is 40 characters. The text of individual buttons is 
separated by a "I" character. In the variable choice the number of the chosen 
button is returned (similar to FORM_ALERT). 

Example: 

ALERT 1,'Please choose|a gadget !',1,'Left|Right.",a% 

ALERT 0,'You haven chosen '+STR${a%)+' gadget ',0," OK *,a% 

An alert box with two gadgets is displayed. After a gadget is chosen a second 
alert box will appear showing which gadget was chosen in the first box. This 
second alert box contains no symbol and no default button. 
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FILESELECT 


FILESELECT title$,oktext$,path$,name$ 

title$,oktext$,path$,: sexp 

name$: svar 

This command places a file selector box on the screen with which the direc¬ 
tory of a disk (ramdisk, harddisk, etc) can be shown and a file can be selected. 
title$ is the action name that is to appear on the title line. "oktextS" passes the 
name of the Ok-gadget (left). It is very simple to change drives using the drive 
gadgets, whose number depends on the drives attached at the time. 

The expression "path$" contains the name of the disk drive and folder that is to 
be shown. If no disk drive is given, the current disk drive will be shown. 
"pathS" can also contain the name of a file that can be selected by simply 
pressing return. If "path$” is an empty string the current drive directory will be 
shown. 

If something is input into the directory path and enter or return pressed the 
corresponding file is searched for. If the new file is not found an empty string 
will be returned in the field of the file selector box. 

"Name$" contains the name of the selected file after which the Ok gadget of 
the selection box is selected. If the Cancel gadget is selected then name$ will 
contain an empty string. 

The format of "name$" corresponds to the conventional hierarchical file sys¬ 
tem that was explained in the "General input and output chapter" in the "file 
management" section. 
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FILESELECT 


Example: 

FILESELECT 'DFOr’.'Load file","Load*,name$ 

IF name$=’“ 

PRINT ‘You have chosen the cancel button." 

ELSE 

IF RIGHT$(name$)=":‘ 

PRINT "You have chosen the OK-button with no data selection.' 

ELSE 

PRINT ‘You have chosen the file named: ‘name$‘ 

ENDIF 

ENDIF 

A file selector box is displayed on the screen and will analyze the choices 
made by the user. 
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10 - Advanced programming 



CLI call / _dosCmd$ 


_dosCmd$ 

run gfabasic [[-] prog ram.gfa [command]] 

GFA-BASIC can be invoked not only by clicking on its icon, but also from 
CLI. In case of the latter the name of a BASIC program can be supplied, 
which program is executed automatically after the loading of GFA-BASIC is 
finished. If the program should only be loaded in the editor but not executed, a 
dash should precede the program name (don’t forget the space!). 

This method can also be employed to invoke BASIC programs from batch 
files. In this case it is possible to follow the BASIC program name with addi¬ 
tional command characters. Within GFA-BASIC these commands are then 
available in the variable _dosCmd$. Parameters can be passed even from the 
Workbench, file names at the very least. To do this, select the GFA-BASIC 
icon while holding down the Shift key and then select the parameter file. The 
whole procedure is then completed by a double click. 
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EXEC 


EXEC command$,in,out 

command$: sexp 
in,out: iexp 

This command starts up a new CLI process. The CLI command is supplied in 
"commands". The parameters "in" and "out" are channel numbers for the 
standard input and output for this CLI process. To keep the same channel use 
the value -1. 


Examples: 

EXEC ":dock“,-1,-1 

Starts the clock (as long as the clock program is in the root directory of the 
current drive). GFA-B ASIC waits until the clock stops (the window is closed). 

EXEC "run dock ANALOG=100,100,200,120 seconds" 

Starts a process parallel with GFA-BASIC. 

If the GFA-BASIC itself is started from CLI with -1 for channel numbers, this 
same CLI window is used as input/output channel for any processes started 
with EXEC. If the GFA-BASIC is started from the Workbench, the EXEC will 
use an additional window (CON:0/0/320/200/NewCLI window) as the output 
device. 
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Library variables 


DosBase 
IntBase 
Gf xBase 
.LayersBase 


These variables contain the address of the corresponding library base. These 
libraries are used internally by GFA-BASIC and are, for this reason, contained 
in main memory. The functions in these libraries can be invoked directly (see 
chapter 11), without having to open the library itself. 

GFA-BASIC currently employs the following libraries: 


.DosBase 

.IntBase 

.GfxBase 

.LayersBase 


DOS library (The AmigaDOS functions). 
Intuition library (Intuition operating system). 
Graphic library (graphic and character functions). 
Layers library (management of character levels). 
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SPRITE 


SPRITE #n,data$ 

SPRITE #n[,""] 

SPRITE #n,x,y 
SPRITE ON 
SPRITE OFF 

b,x,y: iexp 
data$: sexp 

This command puts a hardware sprite on the screen. The sprite is therefore 16 
points wide and has a selectable height. The resolution of the sprite cor¬ 
responds to the lowest screen resolution (320 x 200). Each two bits of the 
sprite definition yield one screen point and define its color. 

The Amiga hardware sprites can be controlled using the sprite command. 
There as 8 sprites with numbers 0-7, where sprite #0 is assigned to the mouse. 

SPRITE #n,data$ defines the appearance of a sprite. The data$ contains there¬ 
fore the bitmap for sprite data. Each row is defined by 4 bytes, the first two 
bytes for the bit plane 0, and the other for the bit plane 1. The height of the 
sprite is calculated by dividing the width of a string by 4. 

SPRITE #n frees up the relevant sprite, that was assigned using SPRITE 
#n,data$. The same goes for SPRITE #n,'"'. 

SPRITE #n,x,y moves the sprite n to the position with coordinates x and y. 
These coordinates are always given in the lowest resolution (320 * 256 or 320 
* 200). Before a sprite can be moved a window or a screen must be opened. 

SPRITE OFF turns off all sprites including the mouse. SPRITE ON turns on 
all defined sprites. 
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SPRITE 


Each pair of sprites (0/1, 2/3 etc.) uses the same color registers for definition 
of sprite colors. These color registers are set for each screen separately. The 
sprites always use the colors registers of the screen which lies behind the 
sprite. The color register of the screen can be changed using SET-COLOR. 


Color register assignment: 


Color bits 
00 

Sprite 0/1 

Sprite 2/3 Sprite 4/5 
always transparent 

Sprite 611 

01 

Reg. 17 

Reg. 21 

Reg. 25 

Reg. 29 

10 

Reg. 18 

Reg. 22 

Reg. 26 

Reg. 30 

11 

Reg. 19 

Reg. 23 

Reg. 27 

Reg. 31 


Example: 

OPENW 1 
a$=STRING$(64,-1) 

SPRITE #2,a$ 

SETCOLOR 23,&hF00 
FOR i%=0 to 200 
SPRITE #2,i%,i% 

PAUSE 1 
NEXT i% 

SPRITE #2 

This program moves a rectangular light red sprite across the screen. 
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STICK / STRIG 


STICK(p) 

STRIG(p) 

m,p: iexp 

The Amiga has two ports for the connection of a mouse and a joystick. Port 0 
can be interrogated for either mouse or joystick coordinates, while port 1 for 
joystick only. 

The function STICK(p) serves to interrogate the joystick position. Using p=0 
reports the position of the joystick in port 0, and using p=l reports the joystick 
in port 1. 



Similarly STRIG(p) determines the status of the fire buttons (TRUE=pressed, 
else FALSE). 

The interrogation of a joystick in port 0 is sent to the Intuition, i.e. the operat¬ 
ing system reacts to the joystick movements as if it were the mouse. 

For compatibility reasons the command STICK has also been implemented, 
has has no effect 
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STICK / STRIG 


Example: 


(interrogate the joystick in port 1, 

REPEAT 

st%=STICK(1) 

fire!=STRIG(1) 

SELECT st% 

CASE 4 
PRINT "left- 
CASE 8 
PRINT -right- 
CASE 2 
PRINT -down- 
CASE 1 
PRINT -up“ 

ENDSELECT 

UNTIL fire! 

WHILE STRIG(I) 

WEND Iwaits for the release of the fire button 
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SAY / TRANSLATE$() 


SAY x$[,m%()] 

TRANSLATES*) 

x$: sexp 

m%(): integer field 

Using the SAY command a character is "articulated" using the Amiga 
phoneme code. This command is mostly used in connection with TRANS¬ 
LATES. The TRANSLATES function converts an english text into phoneme 
codes. For other languages this is often wrong. 

In order for SAY to be operational, a narrator.device must be present in DEVS: 
directory. For TRANSLATES, the translator.library is required in the LIBS: 
directory. 

The output of SAY can be modified using the m% variable. 

m%(0) basic frequency (65-320; default= 110) 

m%(l) inflection (0=normal, l=monotone; default=0) 

m%(2) speech speed (40=400 words per minute; default= 150) 
m%(3) voice type (0=male, l=female; default=0) 

m%(4) sample frequency (5000-28000; default=22200) 

m%(5) volume (0-64; default=64) 

m%(6) channel (value=channel: 0=0, 1=1, 2=2, 3=3, 4=0+1, 5=0+2, 

6=3+1, 7=3+2, 8=0 or 3, 9=1 or 2, 10=0 or 2 and 1 or 2,11=0, 
1,2 or 3; default=10 (stereo) 

Example: 

SAY TRANSLATE$(-I am an Amiga") 
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FD-Files 


The following program will display the enclosed Amiga GFA procedure FD 
files as .LST files. These can then later be loaded and included in your 
programs with the MERGE command. For DOS, Intuition, Graphics, Layers 
etc. (see chapter 11) this is, as a rule, unnecessary. 

DIM a$(15) 

OPEN *i’.#1 ,’DF0:fd1.3/dosJib.fd" 

DO UNTIL EOF(#1) 

LINE INPUT #1,a$ 

IF LEFT$(a$)=’#’ 

SELECT CVL(MID$(a$,3» 

CASE "base" 

SELECT UPPER$(MID$(a$,8)) 

CASE "_DOS" 
l$='_DosBase” 

CASE MAY’ 
l$='_LayersBase" 

CASE ’JNr 
l$=’_lntBase" 

CASE ’_GFX’ 
l$=’_GfxBase’ 

CASE "_SYS" 
l$=’{4}’ 

DEFAULT 

l$=MID$(a$,9)+’%* 

ENDSELECT 
CASE "bias’ 
o%=VAL(MID$(a$,8)) 

CASE ’publ" 

CASE ’priv’ 

ENDSELECT 
ELSE IF LEFT$(a$)=— 

PRINT ’> PROCEDURE *; 
n$=LEFT$(a$,INSTR(a$,’)’)) 
nl$=LEFT$(n$,INSTR(a$.’(’)-1) 

PRINT nl$; 

nr$=MID$(n$,LEN(nl$)+2) 

i%=0 

WHILE LEN(nr$)=1 
a%=INSTR(nr$,’,') 

IF a%=0 
a%=LEN(nr$) 

ENDIF 

a$(i%)=LEFT$(nr$,a%-1) 
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INC i% 

nr$=MID$(nr$,a%+1) 

WEND 

IF i% lit parameters are used 

a%=1 

WHILE a% 
b%=0 

WHILE b%=a% 

IF a$(a%)=a$(b%) 
a$(a%)=a$(a%)+STR$(a%) 
a$(b%)=a$(b%)+STR$(b%) 

ENDIF 
INC b% 

WEND 
INC a% 

WEND 
PRINT *(’; 
j%=0 

WHILE j%-1 
PRINT a$(j%);"%,’; 

INC j% 

WEND 

PRINT a$(j%) 

ENDIF 

PRINT 

r$=MID$(a$,LEN(n$)+2) 

i%=0 

WHILE LEN(r$) 

SELECT ASC(r$) 

CASE "D" 

PRINT ■ m68%(";MID$(r$,2,1 );")=";a$(i%);"%" 

CASE "A" 

PRINT ’ m68%(-;VAL(MID$(r$,2,1))+8r)**;a$(i%);-%’ 
ENDSELECT 
INC i% 
r$=MID$(r$,4) 

WEND 

PRINT * m68%(14)=-;l$ 

PRINT " RCALL M$;'-*;o%r,m68%()' 

ADD o%,6 
PRINT "RETURN’ 

ENDIF 

LOOP 
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For example: 

##baseT ransfatorBase 
##bias 30 
##public 

Translate(inString%.inLength%,outBuffer%,bufforSize%) 
m68%(8)=inString% 
m68%(0)=inLength% 
m68%(9)=outBuffer% 
m68%( 1 )=bufferSize% 
m68{ 14)=T ranslatorBase% 

RCALL TranslatorBase%-30,m68%() 

RETURN 

The only thing missing in the above routine is the DIM m68%(15) and the 
Open Library. 
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Blitter objects 


The Version 3.0 of GFA-BASIC on the Amiga enables the display and usage 
of BOBs (blitter objects). A BOB is a special version of a sprite that can be 
created either with the Amiga Basic object editor or with IFF_TO_BOB .GFA 
program enclosed on the disk. 

These BOBs are well suited for creation of your own fast animation routines; 
knowledge of machine language is not needed. All BOB commands are fully 
compatible with Amiga Basic OBJECT commands with the exception of the 
following, unimplemented, commands: 


COLLISION ON/OFF/STOP 

=COLLISION(-l) does not return the window number. 

A short overview of OBJECT commands follows (Object or Obj is always 
used here to mean Objectnumber). 
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OBJECT.AX obj,value 
OBJECT.AY obj,value 

value: acceleration value in pixels/sec. 

Sets the acceleration of an object in the x and y direction. 

OBJECT.CLIP x0,y0,x1 ,y1 

Sets the clipping rectangle, inside which the BOBs will be displayed. The 
change in window size has no effect on clipping rectangle. 

OBJECT.CLOSE [Obj[,Obj[,Obj]]] 

Deletes objects. Without parameters it deletes all active Amiga GFA-BASIC 
3.0 BOBs. 
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OBJECT.ON [Obj[,Obj[,Obj]]] 

OBJECT.OFF [Obj[,Obj[,Obj]]] 

This will switch the BOBs on or off, where obj is the number of the relevant 
objects with 0 Obj 16. Without parameters the command applies to all BOBs. 

OBJECT.PLANES Obj [,PlacePick[,PlaneOnOff]] 

PlanePick, PlaneOnOff: 8 bit masks 

This defines the BOB colors. PlanePick determines in which bitplane the BOB 
data will be drawn. PlaneOnOff sets or clears the bitplanes not used by Plane- 
Pick (about this refer also to the Amiga Basic manual). 

OBJECT.PRIORITY obj.prlo 

Setting of priority order of BOBs. The BOBs are drawn one on top of the other 
depending on the priority. 

0 ,= Prio ,= 32768 

When no priorities are set the BOBs are drawn in an arbitrary way. 

OBJECT.SHAPE obj.strlng 
OBJECT.SHAPE objl ,obj2 

There are two possible versions of this command: 

1. obj is the number of the string that (for defined BOBs) contains the data 
from either the Amiga Basic Object editor or the IFF_TO_BOB.GFA 
program. 

2. objl is a number of an existing BOB, which will be copied to obj2. 
However, the BOB position, collision handling and the color mask are 
not copied. 
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OBJECT.START [Obj[,...]] 

OBJECT.STOP [Obj[,...]] 

Start or stop BOB movement. Without object numbers the command affects all 
BOBs. 

OBJECT.VX obj,value 
OBJECT.VY obj,value 

value: acceleration value in pixels/sec. 

Sets the acceleration of an object in both the x and y direction. 

OBJECT.X obj,value 
OBJECT.Y obj,value 

Obj: object number 

value: pixel value of coordinates 

Sets the BOB position (x,y) within a window. 

To make a BOB visible the command OBJECT.ON must be used. The object 
movement commences with OBJECT.START after which the acceleration and 
the speed is defined. 

=OBJECT.X{obj) 

/=OBJECT.Y(obj) 

=OBJECT.VX(obj) 

=OBJECT.VY(obj) 

=OBJECT.AX(obj) 

=OBJECT.AY(obj) 

These functions are used to inquire about the position, acceleration and speed 
of given objects. 

ON COLLISION GOSUB proc 

proc: name of a procedure invoked after a collision. 
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System routines 
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Systems calls 


It is possible to call the operating system routines from within GFA-BASIC. 
During the input of these routines, the syntax and the indentation are automati¬ 
cally performed and, if necessary, corrected. Since most functions have 
numerous parameters, this ensures the correct input. 

The interpreter intercepts such invalid input, but it leaves the error handling up 
to the operating system (GURU). 

System functions, that exist in similar form as BASIC commands, are per¬ 
formed using the operating system routine. 

The description of all functions has been reduced to the most important 
aspects. 
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AbortlO(IO_request) 

lo_request: iexp 

Tries to abort the last 1/O-request. No return value. 

Io_request: address of an VO-request-structure. 

AddDevice(adr) 

adriexp 

Adds a new device to the system-device-list and makes it available for all 
tasks. No return value. 

adr: address of the initialized device structure. 

AddFreeListffreeList.memBlock.length) 

freeList, memBlock, length: iexp 

This function adds a specified memory block to a free-memory list.Retum 
value: if an error occurs 0. The error can be interrogated with IoErrO- 

freeList: address of the FreeList structure. 

memBlock: address of the first byte of the memory block to be added to the 
free-memory list- 

length: memory size in bytes. 

AddHead(llst,node) 

list, node: iexp 

Adds a new node to the head of a forward/backward chained linked list No 
return value. 

list: address of the list structure, 
node: address of the node structure 
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AddlntServer(n,adr) 

n, adr: iexp 

Chains a new interrupt server routine to an existing one. No return value. 

n: PAULA (peripherals-sound custom chip) Interrupt bit. 

adr: address of the interrupt structure. 

AddLlbrary(adr) 

adr: iexp 

Adds a new library to the system and makes it available to every task in the 
system. No return value. 

adr: address of the initialized library structure 

AddPort(msgPort) 

msgPort: iexp 

This function adds a message port to the systems message port list and makes 
it available to any task. No return value. 

msgPort: address of the MsgPort structure. 

AddResource(resource) 

resource: iexp 

This function adds a new resource to the system-resource-list and makes it 
available to every task in the system. No return value. 

resource: address of the initialized resource structure. 
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AddTall(llst.node) 

list, node: iexp 

This function adds a new node structure at the end of a doubly linked list. No 
return value. 

list: address of the list structure, 
node: address of the node structure. 

AddTask(taskCB,lnitlalPC,finalPC) 

taskCB, initialPC, finalPC: iexp 

This function adds a new task to the system. No return value. 

taskCB: address of the tasks Control-Block structure. 

initialPC: address of stack start. 

finalPC: address of stack end. 

Allocate(memheader,byteSize) 

memheader, byteSize: iexp 

This function is used to allocate blocks of memory from a task’s own free 
memory list. Return value: If no error occurred the address of the block, other¬ 
wise 0. 

memheader: address of the MemHeader structure. 
byteSize: block size in bytes. 

AllocEnt ry (mem List) 

mem List: iexp 

This function initializes a MemList structure. Return value: If the routine was 
executed successfully the address of the MemList structure is returned. When 
an error occurs the highest bit of the 32 bit values is set 

memList: address of the MemList structure. 
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AltocMem(byteSlze,art) 

byteSize, art: iexp 

This function allocates memory (MALLOC). Return value: Address of the 
memory block or 0 if not available. 

byteSize: Size of the block in bytes. This number is rounded up to the next 

larger block size (a multiple of 8). 
art: memory attributes (e.g. MEMF_CHEP). 

AllocSIg nal(slgnalNum) 

signalNum: iexp 

This function is used to allocate a signal bit from the current task’s pool of 
available signal bits. 

Return value: Bit number 0-31 or -1. 
signalNum: Bit number 0-31 or -1 for no bit. 

AllocTrap(trapNum) 

trapNum: iexp 

Allocates a trap number from the current task’s pool of available trap numbers. 
trapNum: Trap number 0-15 or -1 for no trap. 

AvallMem(art) 

art: iexp 

Returns the free memory. Return value: free memory, 
art: memory attributes 
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Cause(interrupt) 

interrupt: iexp 

This function causes a software interrupt to occur. No return value, 
interrupt: Address of the initialized Interrupt structure. 

CloseDevlce(lo_request) 

lORequest: iexp 

This function informs the system that a device has been cancelled. The device 
will be no longer associated with this task. No return value. 

IORequest address of an initialized I/O Request Block structure. 

CloseLlbrary(llbrary) 

library: iexp 

Closes a function library. No return value, 
library: address of the library structure. 

Deallocate(memHeader,memBlock,byteSize) 

mem Header, mem Block, byteSize: iexp 

This function deallocates memory by returning it to task’s own free memory 
pool. No return values. 

memHeader: address of the MemHeader structure. 
memBlock: address of the memory block to free up. 
byteSize: size of the block in bytes. 
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CreateExtlO(replyport,slze) 

replyport, size: iexp 

This function allocates memory and initializes an extended IO Request struc¬ 
ture. Return value: The address of the IO Request structure. 

replyport: address of an allocated and initialized MsgPort 

size: amount of memory to be reserved for the MsgPort structure. 

CreateProc(name,prl,seg, stack) 

name: iexpseg:iexp 
pri, stack: iexp 

Starts a new process. Return value: Process-ID 

name: process name string, 
pri: process priority (-128 to 127). 
seg: address of the segment (LoadSegO). 
stack: stack size for the process. 

CreateStdlO(replyport) 

replyport: iexp 

Allocates memory and initializes a new IOStdReq structure. Return value: ad¬ 
dress of the structure. 

replyport: address of an initialized Message Port 

DebugO 

Debug activates the ROM-Wack function of the operating system. After this, 
communication is performed through the RS-232-C serial data port at 9600 
baud. 
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DevlceProc(name) 

name: iexp 

DeviceProc determines the address of the device handles specified in "name", 
name: Process name 

Dlsable() 

Disable is very similar to the "Forbid" function. In addition the interrupts are 
disabled. 

DolO(lo_request) 

lo_request: iexp 

This function requests that a device driver perform the I/O command specified 
in the I/O Request Block structure. Return value: when successful 0, otherwise 
the error number. 

Io_request: address of the initialized I/O Request structure. 

EnableO 

Activates interrupts after a "Disable". 

Enqueue(list,node) 

list, node: iexp 

This function inserts or appends a node to the specified system list. No return 
value. 

list: address of the list structure, 
node: address of the node structure. 
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FlndName(start,name) 

start, name:iexp 

FindName searches through a system node list until a node structure with the 
given name is found. Return value:address of the node structure or 0. 

start: address of a node or list structure. 

name: Address of the node structure name, a zero terminated text string. 

FlndPort(name) 

name: iexp 

FindPort searches the system message-port list for a port with the given name. 
Return value: Address of the MsgPort structure or 0. 

name: name of the message port to find, a pointer to a zero terminated text 
string. 

FlndResldent(name) 

name: iexp 

This function attempts to find the address of a resident structure. Return value: 
address of the resident structure or 0. 

name: name of the resident structure, a pointer to a zero terminated text string. 

FindTask(name) 

name: iexp 

Checks all task lists for a task with the give name. Return value: address of the 
TaskControlBlock structure or, if an empty name string is given as input, a 
pointer to the current tasks Control block. 

name: a pointer to the name of the task, a zero terminated text string. 
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ForbldQ 

Forbid stops the task switching. 

FreeEntry(memllst) 

memlist: iexp 

FreeEntry frees all entries of a MemList structure. No return value, 
memlist: address of the MemList structure, which contains the entries. 

FreeFreeList(freelist) 

freelist: iexp 

Frees all entries in the given FreeList structure. No return value, 
freelist: address of the FreeList structure. 

FreeMem(adr,count) 

adrtexp 
count: iexp 

Frees a block of memory, returning it to the system free memory list. Return 
value: size of the memory block in bytes. 

adr: address of the memory block, 
count size of the memory block in bytes. 

FreeRaster(memblock,w,h) 

mem block: iexp 
w, h: iexp 

This function frees a bitplane of a raster bitmap, which was allocated with the 
AllocRasterO function. No return value. 

memblock: address of the bitplane. 

w, h: width and height of the bitplane. 
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FreeSlgnal(sigblt) 

sigbit: iexp 

Frees a previously allocated signal bit No return value, 
sigbit: the released signal bit (0-31). 

FreeTrap(trapnr) 

trapnr: iexp 

Frees an allocated trap number for reuse in a task. No return value, 
trapnr: trap number (0-15). 

GetCC() 

This function gets the condition codes of the 68000 CPU. Return value: code 
bits in DO (0-4). 

GetMsg(Msgport) 

msgport: iexp 

The function gets the next message from the specified message port. After the 
message was received, it should be send back with the ReplyMsgO function to 
signal that it was received correctly. 

MsgPort: address of the MsgPort structure from which the messages is 

to be received. 
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lnitCode(startClass,version) 

flag, version: iexp 

InitCode initializes all resident modules with a specific startClass and version 
number. No return value. 

flag: StartClass. 

version: version number of the resident module. 

lnltRes!dent(resident,segl!st) 

resident, seglist: iexp 

This function initializes a resident module associated with a specific Resident 
structure using the segment list No return value. 

resident: address of a Resident structure 

seglist: address of a segment list for the specified resident module. 

lnitStruct(lnlt,buffer,slze) 

init, buffer: iexp 
size: iexp 

This function will initialize an area of memory. The value in RAM at address 
"init" is used for initialization. No return value. 

init: address of the initialization table, 
buffer address of the memory block to initialize 
size: size of the memory block in bytes. 

lnsert(list,nodel ,node2) 

list, nodel, node2: iexp 

This function inserts a Node structure into a doubly linked list after a given 
node position. No return value. 
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list; address of a list structure which contains the node structure, 
node 1; address of the Node structure to insert. 

node2: address of the Node structure after which "node 1" is to be inserted. 

MakeLibrary(funclnlt,stMakeLlbrary(funclnlt,structinit,libinit, 
size,seglist) 

funcinit, structinit, libinit, seglist: iexp 
size: iexp 

This function constructs a new library. Return value: address of the Library 
structure. 

funcinit: pointer to a table of library routine addresses, 

structinit: pointer to the InitStructO data region, 

libinit: address of the INIT function that must be called before the 

library is added to the system. 

size: the size in bytes of the libraries data area (Library structure data 

and library routines). 

seglist: pointer to an AmigaDOS memory segment list. Used only for 

libraries loaded by AmigaDOS. 

OpenDevlce(devname,number,lORequest,flags) 

devname, number, lORequest, flags: iexp 

This function opens the specified device and initializes the lORequest struc¬ 
ture. Return value: 0 when successful, otherwise an error number. 

devname: name of the device to open, 

number: Device number (0-4). 

lORequest address of the lORequest Block structure which is to be 
initialized. 

flags: special device information. 
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OpenLlbrary(name,version) 

name: iexp 
version :iexp 

This function opens a library and makes it available to the system. Return 
value: Address of the Library structure. 

version: version number of the library. 

OpenResource(name) 

name: iexp 

This function opens a previously installed resource. Return value: address of 
the Resource structure or 0. 

name: resource name. 

Permit () 

Enables the task switching, which was previously disabled with ForbidO- 

Procure(semaphore,message) 

semaphore, message: iexp 

If the semaphore is available, Procure returns a TRUE value and the message 
pointer argument is not used. If the semaphore is already being used, Procure 
returns a FALSE value. 

semaphore: address of the Semaphore structure, 
message: address of the Message structure. 
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PutMsg(msgport, message) 

msgport, message: iexp 

This function adds a message to a given message port queue. No return value. 

msgport: address of the Message Port structure that is to receive the 

message. 

message: address of the Message structure whose contents are to be 

transmitted. 

RawDoFmt(st ring,streamadr,function,buffer) 

string, streamadr, function, buffer: iexp 

This function is used for data formatting. No return value. 

string: address of a zero terminated string, 

streamadr pointer to the unformatted memory area, 
function: address of the output function. 

buffer address of memory area where the formatted data is to be 

written to. 

RawKeyConvert(event,buffer,len,keymap) 

event, buffer, len, keymap: iexp 

Using the specified key table, this function translates a scancode into an ASCII 


code. 


event: 

address of the Input Event structure. 

buffer 

byte buffer. 

len: 

size of the buffer in bytes. 

keymap: 

address of the key table. 
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Rem Devlce(device) 

device: iexp 

Removes an existing device from the system device list. No return value, 
device: address of a device structure. 

RemHead(list) 

list: iexp 

RemHead removes a head Node structure from a list of Node structures, 
list: address of the List structure. 

RemLlbrary(llbrary) 

library: iexp 

Removes an existing library from the system Library list The library cannot 
be used again until it’s added with the AddLibrary function. Return value: 0 if 
no error, otherwise an error number. 

library: address of a Library structure. 

Remove(node) 

node: iexp 

Removes a Node structure from a doubly linked list No return value, 
node: address of the Node structure to be deleted. 
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RemPort(msgport) 

msgport: iexp 

Removes a public message port from the systems message port list No return 
value. 

msgport: address of a MsgPort structure. 

RemResource(resource) 

resource: iexp 

Removes an existing resource from the system resource list. No return value, 
resource: address of the Resource structure. 

RemTall(llst) 

list: iexp 

This function returns the address of the last (tail) Node and removes it from 
the node list Return value: address of the Node structure. 

list: address of the list structure. 

RemTask(task) 

task: iexp 

This function removes a task from the system task ready list, 
task: address of the task structure. 
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ReplyMsg(message) 

message: iexp 

Whenever a message is received in the message port, after it has been 
processed, it should always be sent back. No return value. 

message: address of a Message structure. 

SendlO(IO_request) 

IO_request:iexp 

Requests the device driver to start the command specified in the given 
IORequest Block structure. No return value. 

IOjrequest: address of an initialized IORequest structure. 

SetExept(new,mask) 

new, mask: iexp 

This function defines which of the 32 signal bits will cause exceptions. Return 
value: the old signal bit. 

new: new signal bit. 
mask: 32 bit mask. 

SetFunction(llbrary,funcoffset,funcadr) 

library, funcoffset, funcadr: iexp 

This function inserts a new function in the library. Return value: address of the 
old (replaced) function. 

library: address of the Library structure where the new function is to be 

inserted. 

funcoffset: offset where the new funcEntry vector should go. 
funcadr: address of the function to be inserted. 
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SetlntVector(number, interrupt) 

number: iexp 

interrupt: iexp 

The code and data pointers for this interrupt are set to new values. Return 
value: address of the old Interrupt structure. 

number. PAULA bit number(0-14). 

interrupt: address of the new Interrupt structure. 

SetSlgnal(newsig,slgmask) 

newsig, sigmask: iexp 

SetSignal defines the state of the task’s received signals. Return value: old sig¬ 
nal bit. 

newsig: new signal bit. 

sigmask: 32 bit mask. 

SetSr(new,mask) 

new, mask: iexp 

This function lets you modify the 68000 CPU status register. Return value: old 
status register. 

new: new value for the 68000 CPU status register, 
mask: mask of the bits to be changed. 

SetTaskPri(task,prl) 

task: iexp 
pri: iexp 

SetTaskPri changes the priority of a task. Return value: old priority. 

task: address of the TaskControlBIock structure, 
pri: New priority (-128 to 127). 
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SetWrMsk(rastport,mask) 

RastPort, mask:iexp 

Protects a specified bitplane from overwrite. No return value. 

RastPort: address of the RastPort structure 

mask: specifies which bitplanes should be protected. 

Signal(task,signal) 

task, signal :iexp 

This function signals a task with the signals specified in the function call. No 
return value. 

task: address of the TaskControlBlock structure, 
signaksignal bit. 

SumLibrary(library) 

library: iexp 

Computes a new checksum on a library. No return value, 
library: address of a Library structure. 

SuperState() 

This function causes the 68000 CPU to enter the supervisor mode. 

SwapBitsRastPortCllpRect(rastport,cliprect) 

RastPort, cliprect: iexp 

This function copies the contents of a RastPort into the bitmap of a clipping 
rectangle. No return value. 

RastPort: address of the RastPort structure, 

cliprect: address of the ClipRect structure. 
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UserState(stack) 

stack: iexp 

UserState switches the 68000 CPU back to the user mode. No return value, 
stack: size of the supervisor stack. 

Vacate(semaphore) 

semaphore: iexp 

Opposite of ProcurO- No return value, 
semaphore: address of a semaphore structure. 

Wait(signal) 

signal: iexp 

This function suspends the current task and waits for one or more signals, 
signal: signal bit 

WaitlO(IO_request) 

IO_request: iexp 

This function waits for the specified IORequest to finish. Return value: 0 or an 
error number. 

IO_request: address of an IORequest structure. 
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WaKPort(msgport) 

msgport: iexp 

This function waits for an event from the specified Message port 
msgport: address of the Message structure. 
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AddVSprite(vSpr'te,RastPort) 

vSprite, RastPort: iexp 

Adds a VSprite structure to the current graphics element list 

VSprite: address of VSprite structure. 

RastPort: address of the controlled RastPort structure. 

AddAnimOb(anlmOb,animKey,RastPort) 

animOb, animKey, RastPort: iexp 

Adds an AnimOb structure to the linked list of animation objects. No return 
value. 

animOb: address of the AnimOb structure to be added. 

animKey: address of the first AnimOb structure in the list 

RastPort: address of the RastPort structure. 

AddBop(bob,RastPort) 

bob, RastPort: iexp 

Adds a Bob structure to the current graphics element list No return value. 

bob: address of Bob the structure. 

RastPort: address of the RastPort structure. 

AddFont(textFont) 

textFont: iexp 

Adds a font to the system font list and makes it available to all tasks. No return 
value. 

textFont address of the TextFont structure. 
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AllocRaster( width, height) 

width, height: iexp 

Allocates chip memory for a single bitplane in a raster bitmap. Return value: 
address of the memory block or 0. 

width: width of the bitplane in bits, 

height: height of the bitplane. 

AllocWBObject(wbobject) 

wbobject: iexp 

Allocates all memory necessary for a Workbench object info file. Return 
value: Address of the WBObject structure or 0. 

AndRectRegion(region,rectangle) 

region, rectangle: iexp 

Performs an AND operation between a clipping rectangle and a graphic 
memory area. The result is left in the area defined with the region structure. 

region: address of the region structure, 

rectangle: address of the rectangle structure. 

AndRegionRegion(regionl,region2) 

region 1, region2: iexp 

Performs an AND operation between two regions. The result is stored in 
region2. 

region 1: address of the first Region structure. 

region2: address of the second Region structure. 

Animate(animKey,RastPort) 

animKey, RastPort: iexp 

This function moves an animation object you have created. No return value. 
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animKey: address of the RastPort structure. 

RastPort: address of the RastPort structure 


AreaClrcle(rastport,centerX,centerY,radius) 

RastPort. centerX, centerY, radius: iexp 

Adds a circle to an Arealnfo list. To run the area function, you have to allocate 
memory for the blitter with the InitTmpRas and InitArea functions. Return 
value: 0 or if an error occurred 1. 

RastPort: address of the RastPort structure. 

centerX: x coordinate of the circle center. 

centerY: y coordinate of the circle center, 

radius: the radius of the circle (in pixels). 

AreaDraw(rastport,x,y) 

RastPort, x, y: iexp 

Adds a comer point to a polygon. Return value: 0 or if an error occurred -1. 

RastPort: address of the RastPort structure, 

x: x coordinate of the comer, 

y: y coordinate of the comer. 


AreaElllpse(rastport,centerX,centerY,horiz_radius,vert_radius) 

RastPort, centerX, centerY, horiz_radius, vert_radius: iexp 

Adds an ellipse to the Arealnfo list. Return value: 0 or if an error occurred 1. 


RastPort: 

centerX: 

centerY: 

horiz_radius: 

vert_radius: 


address of the RastPort structure, 
x coordinate of the center, 
y coordinate of the center, 
horizontal radius, 
vertical radius. 
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AreaEnd(rastport) 

RastPort: iexp 

Performs the the vector buffer built by the AreaDraw and AreaMove functions. 
All objects will be drawn. 

RastPort: address of the RastPort structure. 

AreaMove(rastport,x,y) 

RastPort, x, y: iexp 

Defines a new starting point for a polygon. Return value: 0 or if an error oc¬ 
curs-1. 

RastPort: address of the RastPort structure, 

x: new X coordinate, 

y: new Y coordinate. 

AskFont(rastport,textAttr) 

RastPort, textAttr: iexp 

This function returns the TextAttr structure in the RastPort structure with the 
text attribute parameters for the current font. 

RastPort: address of the RastPort. 

textAttr: Address of the TextAttr structure. 

AskSoftStyle(rastport) 

RastPort: iexp 

Returns the style of the RastPort font. Return value: normal = 00000000 (0), 
underlined = 00000001 (1), bold = 000000010 (2), italic = 00000100 (4), ex¬ 
tended = 00001000 (8). 

RastPort: address of the RastPort structure. 
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BltBitMap(srcBltMap,srcX,srcY,destBitMap,destX,destY,sizeX, 
sizeY,minTerm,mask,tempA) 

srcBitMap, srcX, srcY, destBitMap, destX: iexp 
destY, sizeX, sizeY, minTerm, mask, tempA: iexp 

The blitter copies the source BitMap contents into the destination BitMap. 
Return value: number of copied bitplanes. 


srcBitMap: 

srcX: 

srcY: 

destBitMap: 

destX: 

destY: 

sizeX: 

sizeY: 

minTerm: 

mask: 

tempA: 


address of the source BitMap structure. 

x coordinate of the upper left comer in pixels. 

y coordinate of the upper left comer in pixels. 

address of the destination BitMap structure. 

x coordinate of the upper left comer in pixels. 

y coordinate of the upper left comer in pixels 

width in pixels. 

height in pixels. 

logical blitter operand 

blitter mask for interleaved bitplanes. 

address of chip memory buffer (for overlapping rectangles). 


BltBltMapRastPort(sourceBltMap,sourceX,sourceY, destRastPort.de 
stX,destY,sizeX,sizeY,minTerm) 

sourceBitMap, sourceX, sourceY, destRastPort: iexp 
destX, destY, sizeX, sizeY, minTerm: iexp 

The blitter copies the source BitMap contents to the BitMap of a RastPort 
structure. 

soureBitMap: address of the source BitMap structure. 
sourceX: x coordinate of the left upper comer in pixels, 

sourceY: y coordinate of the left upper comer in pixels. 

destRastPort: address of the RastPort structure which contains the 
address of the destination BitMap. 
destX: x coordinate of the upper left comer in pixels. 

destY: Y coordinate of the upper left comer in pixels. 

sizeX: width of the copy area. 

sizeY: height of the copy area. 
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minTerm: logical blitter operand. 

BltClear(mem Block,bytecount, flags) 

memBlock, bytecount, flags: iexp 

The blitter fills a chip memory block with 0. 

memBlock: address of the chip memory block to be filled, 
flags: If bit 1 is set, the bytes per row mode is used. If bit 0 is set, the 

function waits until the blitter is finished, 
bytecount: number of bytes. If bit 1 of the flags isn’t set, there is an even 

number of bytes to clear; otherwise, the lower 16 bits of this 
variable are the number of bytes per row and the upper 16 bits 
are the number of rows. 


BltMaskBitMapRastPort(sourceBitMap,sourceX,source Y.destRastP 
ort,destX,destY,sizeX,slzeY,minterm,bltMask) 

sourceBitMap, sourceX, sourceY, destRastPort: iexp 
destX, destY, sizeX, sizeY, minterm, bltMask: iexp 

The blitter copies the contents of the source BitMap to a bitmap of a RastPort 
and logically combines it with a given masks. 


sourceBitMap: 

sourceX: 

sourceY: 

destRastPort: 

destX: 

destY: 

sizeX: 

sizeY: 

minterm: 

bltMask: 


address of the source BitMap structure, 
x coordinate of the left upper comer in pixels, 
y coordinate of the left upper comer in pixels, 
address of the RastPort structure which contains the 
address of the destination BitMap structure, 
x coordinate of the upper left comer in pixels, 
y coordinate of the upper left comer in pixels, 
width of the copy area, 
height of the copy area 
logical blitter operand, 
blitter mask. 
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BltPattem(rastport,maskBitMap,x1 ,y1 ,maxx,maxy,bytecount) 

RastPort, maskBitMap: iexp 

xl, yl, maxx, maxy, bytecount: iexp 

Performs a blitter operation between a RastPort bitmap and a mask bitmap. 

RastPort: address of the RastPort structure. 

maskBitMap: address of the bitmask 
x 1: X coordinate of the upper left comer in pixels, 

y 1: y coordinate of the upper left comer in pixels, 

maxx: width of the copy area, 

maxy: height of the copy area, 

bytecount: number of bytes per row. 

BltTemplate(source,srcX,srcModulo,destRastPort,destX,destY, 
sizeX,size Y) 

source, srcX, srcModulo, destRastPort, destX, destY, sizeX, sizeY:iexp 
Copies a memory block to a bitmap. 

source: address of the source bitarray. 

scrx: x coordinate of source. 

srcModulo: distance to next line in the array. 
destRastPort: address of the destination RastPort structure. 
destX: x coordinate in the bitmap. 

destY: y coordinate in the bitmap. 

sizeX: width of the copy area. 

sizeY: height of the copy area. 

ChangeSprite(viewPort,simpleSprite,sprltelmage) 

viewPort, simpleSprite, spritelmage:iexp 
Changes sprite data. 

viewport: address of the viewPort structure. 

simpleSprite: address of the simpleSprite structure, 
spritelmage: address of the spritclmage structure. 
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ClearEOL(rastport) 

RastPort: iexp 
Erases a text rectangle. 

RastPort: address of the RastPort structure. 

ClearRectRegion(reglon, rectangle) 

region, rectangle: iexp 

All areas of the region inside a clipping rectangle is cleared. Return value: 
TRUE or FALSE. 

region: address of the Region structure, 

rectangle: address of the Rectangle structure. 

ClearReglon(region) 

region: iexp 

This function clears all clipping rectangles of a graphic region, 
region: address of the Region structure. 

ClipBiit(srcRastPort,srcX,srcY.destRastPort,destX,destY,sizeX, 
sIzeY.mlnTerm) 

srcRastPort, destRastPort: iexp 

srcX, srcY, destX, destY, sizeX, sizeY, minTerm: ivar 

The blitter copies a RastPort bitmap rectangle into another RastPort bitmap. 

srcX: x coordinate of the upper left comer. 

srcY: y coordinate of the upper left comer. 

destRastPort: address of the destination RastPort structure. 
destX: x coordinate of the upper left comer. 

destY: Y coordinate of the upper left comer. 

sizeX: width of copy area. 
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stzeY: height of copy area. 

minTerm: logical blitter operand. 

Copy S B itMap( layer) 

layer: iexp 

Copies the contents of a Superbitmap, to a Layerbitmap. The Layer must first 
be defined as Superbitmap. 

layer: address of the layer structure. 

CWalt(clist,xbeam,ybeam) 

dist: iexp 

xbeam, ybeam: iexp 

CWait adds a new instruction to the Copper Intuition list, waits until the video 
beam has reached the position xbeam,ybeam and performs the instruction. 

clist: address of the UCopList structure, 

xbeam.ybeam: coordinates of the video beam. 

DisownBlitterO 

This function frees the blitter for other tasks to use. No return value. 

DlsposeReglon(reglon) 

region: iexp 

Frees all memory of the Region and all associated Rectangle structures, 
region: address of the Region structure. 
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DoCollision(rastport) 

RastPort: iexp 

Tests all graphic elements for collisions. 

RastPort: address of the RastPort structure. 

Draw(rastport,x,y) 

RastPort: iexp 
x, y: iexp 

Draws a point from the current drawing pen position to the position x,y. 

RastPort: address of the RastPort structure, 

x, y: Drawing coordinates. 

DrawCircle(rast port,x,y,radius) 

RastPort: iexp 
x, y, radius: iexp 

Draws a circle in the specified RastPort drawing mode and colors. 

RastPort: address of the RastPort structure, 

x, y: center of the circle, 

radius: radius of the circle. 

DrawEllipse(rastport,x l y,x_radius,y_radius) 

RastPort: iexp 

x, y. x_radius, y_radius: iexp 

Draws an ellipse. 

RastPort: address of the output RastPort structure, 

x, y: center of the circle. 

x_radius: horizontal radius, 

yjradius: vertical radius. 
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DrawGLIst(rastport,viewport) 

RastPort, viewport: iexp 

The sprites and Bobs of the current graphic elements list will be drawn. 
RastPort: address of the output RastPort 

viewport address of the Viewport structure with which to associate the 
virtual sprite Copper instructions. 

Flood(rastport,mode,x,y) 

RastPort, mode: iexp 
x, y: iexp 

Flood fills a RastPort area with the actual fill pattern in the actual fore and 
background colors. No return value. 

RastPort: address of the RastPort structure. 

mode: If mode=l, only the area that has the same color as the point at 

the coordinates x,y. is filled. If mode=0, the Flood function fills 
pixels if they are not the same as the current AOIPen color 
setting. 

x, y: coordinates for fill start 

FreeColorMap(colormap) 

coiormap: iexp 

Frees the memory of a ColorMap structure. No return value, 
coiormap: address of the ColorMap structure. 
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FreeCopLlst(copllst) 

coptist: iexp 

Frees the memory of a CopList structure. No return value, 
coplist: Address of the CopList structure. 

FreeCprLlst(cprllst) 

cprtist: iexp 

This function frees the memory of a CprList structure. No return value, 
cprlist: address of the CprList structure. 

FreeGBuffers(animob,RastPort,buf) 

animob, RastPort, but: iexp 

This function deallocates all buffers of an animation object previously allo¬ 
cated with the GetBuffers function. 

animob: address of an AnimOb structure. 

RastPort: address of the output RastPort structure, 

buf: buffer address. 

FreeSprite(sprltenr) 

spritenr: iexp 

Frees a hardware sprite for use in other tasks. No return value, 
spritenr sprite number (0-7). 
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FreeVPortCopLists(viewport) 

viewport: iexp 

This function deallocates all memory assigned to all Copper lists connected to 
the given viewport. 

GetColorMap(count) 

count: iexp 

GetColorMap reserves memory and initializes a ColorMap structure. Return 
value: address of the ColorMap structure. 

count: number of color registers. 

GetGBuffers(anlmob,RastPort,buffer) 

animob, RastPort, buffer: iexp 

Allocates memory for all buffers of an animation object Return value: TRUE 
or FALSE. 

animob: address of the AminOb structure 

RastPort: address of the output RastPort 

buffer If TRUE, double buffering is used. 

GetRGB4(cmap,regnr) 

cmap: iexp 
regnr: iexp 

Returns the value of an entry in ColorMap structure’s color table array. 

cmap: address of the ColorMap structure, 

regnr register number (0-63). 
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GetScreenData(buffer,size,type,screen) 

buffer, type, screen: iexp 
size: iexp 

Copies all or part of a Screen structure contents. The function can be used to 
inquire about the screen size and mode. This is mostly used for Workbench 
screen. Return value: TRUE or FALSE. 

buffer address of the memory location that will contain a part of the 
screen structure data. 

size: size of the memory block in bytes. 

type: WBENCHSCREEN (1) or CUSTOMSCREEN (15). 

screen: address of a CUSTOMSCREEN. Will be ignored for type=l. 

GetSprite(spriteadr.spritenr) 

spriteadr: iexp 
spritenr: iexp 

Allocates a hardware sprite. The sprite is not placed on the screen. Return 
value: sprite number or -1 if no sprites are available. 

spriteadr: address of a SimpleSprite structure, 

spritenr number of the sprite (0-7). 
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lnitArea(info, buffer, maxcoord) 

info, buffer: iexp 

maxcoord: iexp 

Initializes an Area list. By the use of Area lists it is possible to display graphic 
elements on the screen directly. No return value. 

buffer address of a memory block for the Area lists, 
maxcoord: maximum number of x,y pairs this buffer will hold. 

lnltBitMap(bltmap l deep,width > helght) 

bitmap: iexp 

deep,width,height: iexp 

Initializes a bitmap. The bitmap bitplanes are not allocated, the calling task 
must do this with the function AllocRasterO- No return value. 

bitmap: address of the BitMap structure, 

deep: bitplane depth (number of bitplanes). 

width.height: bitmap size. 

lnitGels(sprite1 ,sprite2,lnfo) 

sprite 1, sprite2, info: iexp 

Initializes a graphic element list for VSprites. This function should be called 
before the usage of VSprites. No return value. 

sprite 1: address of an empty VSprite structure which marks the beginning 

of the list. 

sprite2: Address of an empty VSprite structure which marks the end of 

the list. 

info: Address of a Gelslnfo structure that is to be initialized. 
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InitGMasks(anlmob) 

animob: iexp 

InitGMask initializes all masks of an AnimOb structure. No return value, 
animob: address of an AnimOb structure. 

InitMasks(sprite) 

sprite: iexp 

This function initializes the borders and collision masks of a virtual sprite. No 
return value. 

sprite: address of a VSprite structure. 

InitRastPort(rastport) 

RastPort: iexp 

This function initializes a RastPort structure. All variables of the RastPort 
structure will be zeroed. The value for FgPen, AOlPen and LinePtn is -1. The 
drawing mode JAM2 and the drawing font depend on the resolution Topaz 80 
or Topaz 60. No return value. 

RastPort: Address of the RastPort structure. 

lnltTmpRas(tmpras,buffer,slze) 

tmpras, buffer: iexp 
size: iexp 

This function initializes a chip memory block for use with the Area functions. 
This memory block is used by all Area functions and must be allocated. No 
return message. 

tmpras: address of a TmpRas structure. 

buffer address of the chip memory block for the Area functions. 

size: size of the chip memory block in bytes. 
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InitView(view) 

view: iexp 

InitView fills a View structure with default values. No return value, 
view: address of a View structure. 

InitVPort(viewport) 

viewport: iexp 

This function clears all variables in a View structure. No return value, 
viewport: address of the ViewPort structure to initialize. 

lnstallClipReglon(layer,region) 

layer, region: iexp 

InstallClipRegion defines a clipping rectangle within a layer. All graphic out¬ 
put to this layer will be clipped. Return value: address of the last Region struc¬ 
ture or 0. 

layer: address of the Layer structure. 

region: address of the Region structure which contains the coordinates 

of the clipping rectangle. 

LoadRGB4(vlewport,colors,count) 

viewport, colors: iexp 
count: iexp 

This function assigns a set of RGB color register values to the specified View- 
Port. No return value. 

viewport: address of the ViewPort structure, 

colors: address of the colortable in memory, 

count: number of color registers. 
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LoadVlew(view) 

view: iexp 

Uses a Copper instruction list to create the current display screen view. No 
return value. 

view: address of the View structure. 

LocklBase(number) 

number: iexp 

Grabs an Intuition internal semaphore so that your program can examine the 
IntuitionBase structure safely. Return value: a four byte integer value, needed 
to free that lock with the UnLocklBaseQ function. 

number: reserved for future versions. Should be set to 0. 

MakeVPort(vlew,viewport) 

view, viewport: iexp 

This function creates Dual Playfields. If the DUALPF bit is set in the Modes 
parameter in the View structure, there must be a second Raslnfo structure 
pointed to by the first Raslnfo structure. No return value. 

view: address of the View structure, 

viewport: address of the ViewPort structure. 
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MenuNum(code) 

code: iexp 

Returns the number of the selected menu. Return value: menu number. 

code: value of a code variable in an IntuiMessage structure or value of 
MENU(2). 

Move(rastport,x,y) 

RastPort: iexp 
x, y: iexp 

Places the graphic pen at a new position within the output RastPort No return 
value. 

RastPort: address of the RastPort structure, 

x, y: new coordinates for the graphic cursor. 

MoveSprite(viewport,spriteadr,x,y) 

viewport, spriteadr: iexp 
x, y: iexp 

Moves a hardware sprite to the position x,y. No return value. 

spriteadr: address of the SimpleSprite structure, 

x, y: new sprite coordinates. 

MrgCop(vlew) 

view: iexp 

Fills the Copper Instruction list with new commands. No return value, 
view: address of the View structure. 
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NewRegion() 

NewRegion creates a Region structure of size 0. Return value: Address of the 
new Region structure. 

OrRectRegion(region t cliprect) 

region, diprect: iexp 

This function ORs a graphic area with a clipping rectangle area. The result of 
the operation is stored in the graphic area. No return value. 

region: address of the Region structure, 

cliprect: address of the Rectangle structure. 

OrReglonRegion(reglon1 ,region2) 

regionl, region2: iexp 

This function performs a logical OR operation between two regions. The result 
is stored in the second region. No return value. 

regionl: address of the first Region structure. 

region2: address of the second Region structure. 

OwnBlitterO 

This function prevents other programs from accessing the blitter. 

PolyDraw(rastport,count,cooradr) 

RastPort, cooradr: iexp 
count: iexp 

Draws a polygon with "count" comers. No return value. 

count: number of coordinate pairs. 

cooradr: address of memory which contains the coordinates. 
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QBIit(blitnode) 

blitnode: iexp 

QBlit links a BlitNode structure at the tail end of the current blitter list and 
then performs the blitter routine which is assigned to the BlitNode structure. 
No return value. 

blitnode: address of a BlitNode structure. 

QBSBIit(blltnode) 

blitnode: iexp 

QSBlit synchronizes the blitter operation with the video beam scanning posi¬ 
tion. No return value. 

blitnode: Address of a BlitNode structure. 

RasSlze(w,h) 

w, h: iexp 

This function calculates the size of a raster bitplane. Return value: size in 
bytes. 

w, h: width and height of the bitplane. 

ReadPixel(rastport,x,y) 

RastPort: iexp 

x, y: iexp 

Returns the color register number of the pixel at given coordinates. Return 
value: color number of 1. 

RastPort: address of the RastPort structure where the pixel is. 

x, y: pixel coordinates. 
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RectFill(rastport,x1 ,y1 ,x2,y2) 

RastPort: iexp 
x1,y1,x2,y2: iexp 

This function draws a filled rectangle with current fill pattern, drawing mode 
and colors. 

RastPort: address of the output RastPort structure, 

x 1, y 1: upper left comer of the rectangle. 

x2, y2: lower right comer of the rectangle. 

RemlBob(bob,RastPort,viewport) 

bob, RastPort, viewport: iexp 

RemIBob removes a Bob structure from the graphic element list. No return 
value. 

bob: address of a Bob structure. 

RastPort: address of a RastPort structure, 
viewport: address of a ViewPort structure. 

RemVSprlte(sprite) 

sprite: iexp 

Removes a VSprite structure from the graphic element list. No return value, 
sprite: address of the VSprite structure. 
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ReportMouse(window,true) 

window, true: iexp 

This function tells Intuition whether to report mouse movements in a window. 
No return value. 

window: address of the Window structure, 

true: TRUE or FALSE specifying whether to turn the reporting 

on or off. 

ScrollRaster(rastport,deltax,deltay,x,y,w,h) 

RastPort: iexp 

deltax, deltay, x, y, w, h: iexp 

Scrolls an area of a RastPort No return value. 

RastPort: address of the RastPort structure, 

dx, dy: scroll amount in pixels, 

x, y: upper left comer of the scroll area, 

w, h: lower right comer of the scroll area. 

ScrollVPort(vlewport,deltax,deltay) 

viewport: iexp 
deltax, deltay: iexp 

This function scrolls a Screen. No return value. 

viewport address of the ViewPort structure on the Screen, 

deltax, deltay: new coordinates relative to the old. 

SetAfPt(rastport,data,count) 

RastPort, data: iexp 
count: iexp 

Sets the area fill pattern for areas filled with the area fill drawing functions and 
the RectFillO function. 
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RastPort: address of a RastPort structure. 

data: address of the memory location containing the fill pattern, 

count: 2 A count, or number of words in this data area. 

SetAPen(rastport,nr) 

RastPort: iexp 
nr: iexp 

Sets the foreground drawing color. No return value. 

RastPort: address of the RastPort structure, 

nn color register number. 

SetBPen(rastport,nr) 

RastPort: iexp 
nr. iexp 

Sets the background drawing color. No return value. 

RastPort: address of the RastPort structure, 

nr color register number. 

SetCollisfon(number,routine,gelsinfo) 

number: iexp 

routine, gelsinfo: iexp 

This function sets a pointer to a user collision handling routine. No return 
value. 

number: number of the function (0-15). 

routine: address of the routine, 

gelsinfo: address of a Gelsinfo structure. 
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SetOrMd(rastport mode) 

RastPort: iexp 
mode: iexp 

Sets the drawing mode. No return value. 

RastPort: address of the RastPort. 

mode: drawing mode (the same as in GRAPHMODE). 

SetDrPt(rastport,data) 

RastPort, data: iexp 

Sets a special line pattern. No return value. 

RastPort: address of the RastPort structure, 

data: 16 bit value, the line fill pattern. 

SetFont(rastport,textfont) 

Resets the text font parameters currently defined in a RastPort structure to 
those in the specified TextFont structure. Return value: 0 if no error. 

RastPort: address of the RastPort structure, 

textfont: address of the TextFont structure. 

SetOPen(rastport,register) 

RastPort: iexp 
register: iexp 

This function sets the outline pen (AOlPen) color for text and area outlines. 
No return value. 

RastPort: address of the RastPort structure, 

register: color register number. 
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SetRast(rast port, register) 

RastPort: iexp 
register: iexp 

Sets the entire contents of the specified raster to the specified pen color. No 
return value. 

RastPort: address of the RastPort structure, 

register: color register number. 

SetRGB4(viewport,register,red,green,blue) 

viewport: iexp 

register, red, green, blue: iexp 

This function stores the color definition value in the Colortable array for this 
viewport. No return value. 

viewport address of the Viewport structure. 

register: A pen number for one color register, ranges from 0 to 31. 

red, green, blue: Intensity, ranges from 0 to 15. 

SetRGB4CM(colormap, register, red, green, blue) 

colormap: iexp 

register, red, green, blue: iexp 

Sets a colormap to a specified color number. No return value. 

colormap: address of the ColorMap structure, 

register: color register number, ranges from 0 to 31. 

red, green, blue: desired color value (0-15). 

SetSoftStyle(rastport, new, mask) 

RastPort, new, mask: iexp 

Sets a new display mode for a font selected SetFont() function. Return value: 
the same as in "mask". 


System routines 


11-49 




Graphics-Library 


RastPort: address of the RastPort structure, 

new: new display mode, (refer to AskSoftStyle). 

mask: bitmask of bits to change. 

SortGLIst(rastport) 

RastPort: iexp 

Sorts the VSprite list by Y coordinates. No return value. 

RastPort: address of the RastPort structure. 

Text(rastport,text,length) 

RastPort: iexp 
text, sexplength: ivar 

Writes the specified text to the RastPort starting at the current cursor position. 
Return value: 0, if no error occurred 

RastPort: address of the RastPort structure, 

text: pointer to the text string, 

length: number of characters in the suing. 

TextLength(rastport,text,length) 

Calculates the length of a text suing in pixels. The length is based on the at- 
Uibutes in the TextFont suucture (rastport structure). Return value: length of 
the suing in pixels. 

RastPort: address of the RaslPort suucture. 

text: address of the text suing. 

length: number of characters in the text suing. 
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Translate(text,length,phoneme,outlength) 

text: iexp 

length, phoneme, outlength:iexp 

Translates the specified text into phonetic text for the speech output. 

text: text to be converted, 

sexplength: length of text to convert 

phoneme: address of a memory block which will contain the translation, 

outlength: length of memory area for converted text. 

UCopperLlstlnit(clist,instnr) 

dist: iexp 

instnr: iexp 

This function initializes a UCopList structure. This structure is used to send 
the Copper instructions. 

clist: address of the UCopList structure, 
instnr: maximum number of instructions. 

VBeamPos() 

Returns the current Y position of the video beam. 

ViewAddress() 

This function returns the address of a View structure. 
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ViewPortAddress(wlndow) 

window: iexp 

Returns a pointer to specified window’s ViewPort structure. 

WaitBlit() 

This function halts all tasks until the Blitter is free again. 

WaltBOVP(vlewport) 

viewport: iexp 

Waits until the video beam has reached the beginning of the specified screen 
(vertical retrace). 

viewport: address of the ViewPort structure. 

WrltePlxel(rastport,x,y) 

RastPort: iexp 
x, y: iexp 

This function sets a single pixel in color specified with SetAPen. 

RastPort: address of the RastPort structure, 

x, y: pixel coordinates. 

XorRect Reg io n( reg lo n, rect) 

region, rect: iexp 

This function performs an XOR operation between a clipping rectangle and a 
region. The result is stored in the region. 

region: address of the Region structure, 

rect address of the ClipRect structure. 
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XorReglonRegion(reglonl,region2) 

regionl, region2: iexp 

This function performs an EOR operation between two regions. The result is 
stored in the second region. 

region 1: address of the first region structure. 

region2: address of the second Region structure. 
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BumpRevlsion(newBuf,oidName) 

rtewBuf, oldName: iexp 

This function produces different names for copied files. Return value: Size of 
the new name. 

newBuf: address of the new name (max. 32 bytes; 0 byte at the end). 

oldName: address of the old name (max. 32 bytes; 0 byte at the end). 

CloseWorkBench() 

Closes the Workbench screen. Return value: TRUE or FALSE. 

FindToolTypes(tools,typename) 

tools, typename: iexp 

This function searches a ToolType array for a given name. Return value: ad¬ 
dress of the first found toolname. 

tools: address of the ToolType array. 

typename: address of a literal character string to search for in the ToolType 

array. 

FreeDiskObject(object) 

object: iexp 

Frees the memory used by an Info file. No return value, 
object: address of a DiscObject structure. 


11 -54 


GFA-BASIC 3.0 Amiga 




Workbench-Library 


FreeWBObject(wbobject) 

wbobject: iexp 

Frees up all of the memory previously allocated to the specified Workbench 
object info file. It also frees the memory assigned to the WBObject structure. 
No return message. 

wbobject address of the WBObject structure. 

GetDiskObject(name) 

name: iexp 

Reads a disk object info file from disk into memory. Return value: address of 
the loaded structure. 

name: name of the file whose object structure will be loaded. 

Getlcon(name,diskobject,freelist) 

name: iexp 

diskobject, freelist: iexp 

The only difference between this function and the function GetDiskObjectO is, 
that Getlcon allows you to specify the RAM location for the DiskObject and 
FreeList structures. Return value: TRUE or FALSE. 

name: pointer to the filename of the disk info file you want to load, 

diskobject: address of an initialized DiskObject structure, 
freelist: address of the FreeList structure. 

GetWBObject(name) 

name: iexp 

Reads information about a Workbench object in a WBObject structure. Return 
value: address of the WBObjcct structure. 

name: pointer to the file name of the Workbench object info file you 

want to load. 
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MatchToolValue(stradr1 ,stradr2) 

stradrl, stradr2:iexp 

Searches a ToolTypes character string array for a specific substring. Return 
value: TRUE or FALSE. 

stradr 1: address of the ToolType array. 

stradr2: pointer to the substring you are searching for. 

OpenWorkBenchO 

This function tries to open the Workbench screen. Return value: TRUE or 
FALSE. 

PutDiskObject(name,diskobject) 

name: iexp 
diskobject: iexp 

Saves a DiskObject structure in an Info file. Return value: TRUE or FALSE, 
name: file name. 

diskobject: address of the disk object structure. 

Putlcon(name,diskobject) 

name: iexp 
diskobject: iexp 

Saves the DiskObject structure in an Info file. Return value: TRUE or FALSE. 

name: file name. 

diskobject address of diskobject structure. 
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PutWBObject(name.wbobject) 

name: iexp 
wbobject: iexp 

Saves the WBObject structure in the Info file. Return value: TRUE or FALSE, 
name: file name. 

wbobject address of the WBObject structure. 

WBenchToBack() 

The Workbench screen is moved to the background so that it is covered by 
other screen. 

WBenchToFrontO 

Moves the Workbench screen to the foreground. 


System routines 


11-57 



Intuition-Library 


ActivateGadget(gadget,window,requester) 

gadget, window, requester: iexp 

This function activates a String gadget within a window or a requester. Return 
value: TRUE when no error, otherwise FALSE. 

gadget: address of the String gadget structure, 

window: address of the window structure where the gadget will be 

displayed. 

requester: address of the requester structure or 0. 

ActivateWindow(window) 

window: iexp 

This function will activate a window, 
window: address of the window structure. 

AddGadget(pointer,gadget,position) 

pointer, gadget, position: iexp 

With this function a gadget is inserted in the gadget list of a screen or a win¬ 
dow. Return value: gadget position within the list. 

pointer address of the screen or window structure, 
gadget: address of the gadget structure. 

position: index of the gadget in the list The first gadget is numbered 0. 

AddGList(wlndow,gadget,position,number_gadgets,requester) 

window, gadget, position, number_gadgets, requester: iexp 

With this function several gadgets can be inserted in the gadget list of a win¬ 
dow or a requester. Return value: index of the gadget list 

window: address of a window structure. 

gadget: address of the first gadget in the gadget list. 

position: gadget index of where the new gadgets will be inserted. 
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number_gadgets: number of gadgets to insert 

requester: address of the requester structure. 

AllocRemember(rememberKey,size,art) 

rememberKey, size, art:iexp 

This function reserves memory and chains it to a list The individual memory 
blocks in this list can be release using the function FreeRememberO- Return 
value: memory block address or 0. 

rememberKey: address of the Remember structure. 0 on first call, 

size: memory area size in bytes, 

art: memory attribute. 

AlohaWorkbench(msgport) 

msgport: iexp 

AlohaWorkbench turns on the Workbench monitoring for Intuition. Whenever 
the Workbench is clicked the assigned MessagePort will contain the message 
(Class) WORKBENCHMESSAGE. No return value. 

msgport: address of the message port which should receive the message. 

AutoRequest(wi nd .bodText ,posText,negText,posFlag s,neg Flag s, 
wldth.height) 

wind, bodText, posText, negText, posFlags, negFlags, width, height:iexp 

This function opens a SysytemRequest and waits for user activity. Return 
value: TRUE or FALSE. 

wind: address of the window structure. 

bodText: address of the IntuiText structure. 

posText: address of the second IntuiText structure (OK gadget). 

negText: address of the third IntuiText structure (Cancel gadget). 

posFlags: IDCMP flags. 
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negFIags: IDCMP flags. 

width: requester width in pixels. 

height: requester height in pixels. 

BeginRefresh(window) 

window: iexp 

This function is needed for (simple-refresh) windows and informs Intuition of 
a window refresh start. It calls the BeginUpdateO function. No return value. 

window: address of the window structure. 


BulldSysRequest(window,bodyText,positivText,negatlvText,IDCMPF 
lags,width,height) 

window, body Text, positivText, negativText, IDCMPFIags: iexp 
width, height: iexp 

This function opens a requester in a window and waits for user activity. If no 
window address is given the Intuition itself will create a window for the re¬ 
quester. Return value: address of the window structure. 


window: 

bodyText: 

positiveText: 

negativeText: 

IDCMPFIags: 

width: 

height: 


address of the window structure or 0. 
address of the IntuiText structure, 
address of the second IntuiText structure, 
address of the third IntuiText structure. 
IDCMPFIags for the window, 
requester width, 
requester height. 


ClearDMRequest(wlndow) 

window: iexp 

This function deletes a DoubleMenu requester. Return value: TRUE or 
FALSE. 

window: address of the window structure. 
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ClearMenuStrip(window) 

window: iexp 

Deletes a menu list from a window. No return value, 
window: address of the window structure. 

ClearPolnter(window) 

window: iexp 

Sets the appearance of the mouse pointer from mouse images defined in Sys¬ 
tem Preferences. No return value. 

window: address of the window structure. 

ClearScreen(rastport) 

RastPort: iexp 

Deletes a RastPort at current cursor position. No return value. 

RastPort: address of the RastPort structure. 

CloseScreen(screen) 

screen: iexp 

Closes a screen and releases its memory. No return value, 
screen: address of the screen structure. 

CloseWindow(wlndow) 

window: iexp 

Closes a window and releases its memory. No return value, 
window: address of the window structure. 
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Current Time(Seconds,Micros) 

Seconds, Micros’ iexp 

Returns the actual system time in seconds and milliseconds. No return value. 

Seconds: address of a variable for seconds. 

Micros: address of a variable for milliseconds. 

Display Alert(alertNumber, string, height) 

alertNumber, height: iexp 
string: iexp 

This function opens an Alert box on the screen. Return value: TRUE or 
FALSE. 

alertNumber: number of the alert communication type, 
string: message string, 
height: number of lines. 

DlsplayBeep(screen) 

screen: iexp 

Flickers the screen and serves as a visual warning. No return value. 

screen: address of the screen structure. When screen address of 0 is 

given all screens will flicker. 

DoubleClick(s_sek,s_mic,e_sek,e_mic) 

s_sek, s_mic, e_sek, e_mic: iexp 

Doubleclick determines if a double click of the left mouse button has oc¬ 
curred. The result is based on the setting in the System Preferences. The start 
and end timer can be determined with CurrentTime function. Return value: 
FALSE, if the time of the double click is too long, otherwise TRUE. 

s_sek: start second. 

s_mic: start microsecond. 
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e_sek: end second. 

e_mic: end microsecond. 

DrawBorder(rastport,border,x_off,y_off) 

RastPort, border: iexp 
x_off, y_otf: iexp 

Using this function whole Border structures can be drawn. During the drawing 
the visual hierarchy is observed. No return value. 

RastPort: address of the output RastPort 

border: address of the first Border structure. 

x_off,y_off: offset coordinates that are added to the start coordinates of the 
Borders. 

Drawlmage(rastport, Image, x_off,y_off) 

RastPort, image: iexp 
x_off, y_off: iexp 

Draws Images in a screen or window. If the Image structures are stacked the 
complete Image list will be redrawn. No return value. 

RastPort: address of the output RastPort 

image: address of the first Image structure. 

x_off,y_off: offset coordinates that are added to the start coordinates of the 
Images. 

EndRefresh(wlndow,complete) 

window, complete: iexp 

The redrawing of a Simple-Refresh window is terminated. A BeginReffeshO 
function must have been called beforehand. No return value. 

window: address of the window structure. 

complete: TRUE or FALSE. Indicates whether the window Bitmap will be 

drawn complete or in part 
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EndRequest(requester.wlndow) 

requester, window: iexp 

This function deletes the specified requester from the window. No return 
value. 

requester: address of the requester structure, 

window: address of the window structure. 

FreeRemember(remember,flag) 

remember, flag:iexp 

Deletes either a Remember structure or a stacked (overlaid) memory block in a 
structure. No return value. 

remember: address of the Remember structure. 

flag: l=delete memory, else delete Remember structure. 

FreeSysRequest(wi ndow) 

window: iexp 

Deletes all requesters created with BuildSysRequestO function. No return 
value. 

window: address of window structure. 
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GetDefPrefs(buffer,byte) 

buffer, byte:iexp 

Reads the System Preferences from the disk. No return value. 

buffer address of previously reserved memory buffer, 
byte: number of bytes to copy. 

GetPrefs(buffer.byte) 

Reads the System Preferences from the memory. No return value. 

buffer address of previously reserved memory buffer, 
byte: number of bytes to copy. 

InitRequester(requester) 

requester: iexp 

Initializes a request structure. This function does not display the requester on 
the screen. No return value. 

requester: address of the Requester structure. 

IntulTextLength(lntuitext) 

intuitext: iexp 

This function calculates the length of an IntuiText string in pixels. The length 
of the string is stored in the TextAttr structure of the IntuiText structure. 
Return value: the length of strings in pixels. 

intuitext: address of an IntuiText structure. 
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Intultlon(enev) 

enev: iexp 

This function presents the Intuition with a list of Input Event structures. Ac¬ 
cording to the documentation this function should not be used. Return value: 
address of the fust structure in the Input Event list. 

ltemAddress(menunr,itemnr) 

menunr, itemnr: iexp 

ItemAddress returns the address of memory which contains the required menu 
entry. Return value: address of Menultem structure. 

menunr: number of the menu where the entry is located. 

itemnr: number of the entry whose Menultem address is to be returned. 

MakeScreen(screen) 

screen: iexp 

Creates an output screen. No return value. 
screen:address of the screen structure. 

ModifylDCMP(window.flag) 

window, flag: iexp 

This function modifies the IDCMP flag for given window. No return value. 

window: address of the window structure, 

flag: new IDCMP flags. 
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ModifyProp(gadget,window,requester,flags,hpot,vpot,hbody, 
vbody) 

gadget, window, requester, flags: iexp 
hpot, vpot, hbody, vbody: iexp 

This function modifies the settings for a Proportional gadget. The gadget will 
be redrawn after this function is invoked. No return value. 


gadget: 

window: 

requester: 

flag: 

hpot: 

vpot: 

hbody: 

vbody: 


address of the proportional gadget 
address of the window structure. 

address of the requester structure. In case of a window gadget the 

requester must be set to 0. 

new proportional flags. 

new horizontal position of the sliders. 

new vertical position of the sliders. 

new width 

new height 


MoveScreen(screen,deltax,deltay) 

screen: iexp 
deltax, deltay: iexp 

Moves the screen using the deltax and deltay values. No return value, 
screen: address of the screen structure. 

deltax.deltay: new screen coordinates, relative offset from old coordinates. 


MoveWindow(window, deltax, deltay) 

window: iexp 

deltax, deltay: iexp 

Move the window using the delax and deltay values. No return value, 
window: address of the window structure. 

deltax.deltay: new window coordinates, relative offset from old coordinates. 
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OffGadget(gadget,window,requester) 

gadget, window, requester: iexp 

The given gadget is switched off, which will cause it to be overwritten to indi¬ 
cate that it was deactivated. The function applies only to gadgets that display 
an Imagebit graphic that cannot otherwise be deleted. No return value. 

gadget: address of the gadget structure, 

window: address of the window structure. 

requester: address of the requester structure. In case of a window gadget it 

should be set to 0 

OffMenu(wlndow,menunr) 

window: iexp 

menunr: iexp 

Closes a menu so that even though it is still visible it cannot be selected. No 
return value. 

window: address of the window structure, 

menunr: menu number 

OnGadget(gadget,window,requester) 

gadget, window, requester: iexp 

Reactivates a gadget that was switched off using OffGadget. No return value. 

gadget: address of the gadget structure, 

window: address of the window structure: 

requester: address of the requester structure (for requester gadgets only). 
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OnMenu(wlndow,menunr) 

window: iexp 

menunr: iexp 

Reactivates a menu that was switched off using OffMenu. No return value. 

window: address of the window requester, 

menunr: number of the menu to reactivate. 

OpenScreen(newscreen) 

newscreen: iexp 

Displays a new screen on the monitor. Return value: address if the screen 
structure or 0. 

newscreen: address of the NewScreen structure. 

OpenWindow(newwlndow) 

newwindow: iexp 

Opens a new window on the screen specified in the NewWindow structure. 
Return value: address of Window structure. 

newwindow: address of NewWindow structure. 

PrlntlText(rastport,ltext,x_off,y_off) 

RastPort, itext: iexp 
x_off, y_off: iexp 

This function displays on the RastPort the TextString in the mode specified in 
the IntuiText structure. If the given structure is overlaid with other structures 
they will all be redisplayed. No return value. 
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RastPort: address of the RastPort structure on which the text will be 

displayed. 

itext: address of the first IntuiText structure. 

x_off.y_off: coordinates of where to output all texts. 

RefreshGadgets(gadget,window,requester) 

gadget,window,requester): iexp 

Redraws the gadget list of a window or requester. All components of the 
gadget in the list are redrawn. No return value. 

gadget: address of the first Gadget structure, 

window: address of the first Window structure, 

requester: address of the Requester structure or 0. 

RefreshGLIst(gadget,window,requester,count) 

gadget, window, requester: iexp 
count: iexp 

Redraws the gadget list of a window or requester. Only the number of gadgets 
in "number" are drawn. No return value. 

gadget: address of the first Gadget structure, 

window: address of the Window structure, 

requester: address of the requester structure or 0. 

count: number of gadgets to be redrawn. 
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RefreshWindowFrame(window) 

window: iexp 

Refreshes the contents of a window. No return value, 
window: address of the Window structure. 

RemakeDisplayO 

This function refreshes all current Screen Viewports. 

RemoveGadget(wlndow,gadget) 

window, gadget: iexp 

Removes a gadget from a Window gadget list. 

returns: position of a gadget in the list, 

window: address of the Window structure, 

gadget: address of the Gadget structure. 

RemoveGUst(window,gadget, count) 

window, gadget: iexp 

Deletes a "number" of gadgets from a Window gadget list. Return value: posi¬ 
tion of the first gadget in the list. 

window: address of the Window structure, 

gadget: address of the Gadget structure, 

count: number of gadgets to delete. 

Request^ requester, window) 

requester, window: iexp 

Displays a requester in a window. The requester must be initialized beforehand 
using the InilRequestcr() function. Return value: TRUE or FALSE. 
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requester: address of the Requester structure, 

window: address of the Window structure. 

RethinkDisplayO 

This function serves to refresh the connections between screens as well as 
Copper display list. 

ScreenToBack(screen) 

screen: iexp 

The screen is moved to background so that it becomes covered by other 
screens. No return value. 

screen: address of a Screen structure. 

ScreenToFront(screen) 

screen: iexp 

The screen is moved to foreground so that any other screens are displayed be¬ 
hind it. No return value. 

screen: address of a Screen structure. 

SetDMRequest(window,requester) 

window, requester: iexp 

Displays a Double Menu requester on the screen. Return value: TRUE or 
FALSE. 

window: address of the Window structure, 

requester: address of the Requester structure. 

SetMenuStrlp(window,menuadr) 

window, menuadr: iexp 

Sets the menu list for the given window. No return value. 
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window: address of the Window structure, 

menuadr: address of the first Menu structure. 

SetPolnter(window,data,height,width,x,y) 

window, data: iexp 
height, width, x, y: iexp 

Sets a window specific mouse pointer. No return value. 

window: address of the Window structure, 

data: address of the Sprite data for the new mouse pointer. 

height,width: the height and width of the mouse pointer in pixels. 
x,y: The relative coordinates of the action point (hot-spot). 

SetPrefs(pref,count,mode) 

pref, count, mode: iexp 

This function saves the System Preferences to disk or in previously reserved 
memory block. 

pref: address of the memory block that contains the new data. 

count: size of the memory block. 

mode: 0=change in RAM, l=save to disk. 

SetWindowTitles(wlndow,wtitle,stitle) 

window: iexp 

wtitle, stitle: iexp 

This function sets a new window title. The new screen title can also be 
specified. This title will then be displayed whenever the window is activated 
with the mouse. No return value. 

window: address of the Window structure. 

wtitle: new window title. 

stitle: new window specific screen title. 
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Shiftltem(code) 

code: iexp 

Returns the number of selected menu entries. Return value: number of menu 
entries. 

code: 16 bit code variable from a message structure. 

Shift Menu(code) 

code: iexp 

Returns the number of selected menus. Return value: the number of menus, 
code: 16 bit code variable from a message structure. 

ShowTitle(screen,mode) 

screen: iexp 
mode: iexp 

This function is used to determine whether the Screen title list will be shown 
in background or the foreground of the Backdrop windows. 

window: address of the Window structure. 

mode: l=show the title list in front of Backdrop window, otherwise 0. 

SizeW!ndow(window,deltax,deltay) 

window: iexp 

deltax, deltay: iexp 

A window can be enlarged or shrunk using this function. No return value. 

window: address of the Window structure, 

deltax,deltay: coordinates of the new size, relative to old. 
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UnlocklBase(lockvalue) 

tockvalue: iexp 

Opposite of LockIBase. No return value. 

lockvalue: the value returned from LockIBase function. 

WlndowLlmlts(wlndow,minx,miny,maxx,maxy) 

window. iexp 

minx, miny, maxx, maxy: iexp 

Resets the size limits of a window. Return value: TRUE or FALSE. 

window: address of the Window structure, 

minx,miny: minimum window size, 
maxx.maxy: maximum window size. 

WlndowToBack(wlndow) 

window: iexp 

Moves a window to background so that it becomes covered, fully or in part, by 
other windows. No return values. 

window: address of the Window structure. 

WlndowToF ront(wi ndow) 

window: iexp 

Sets the window in from of all other windows. No return value, 
window: address of the Window structure. 
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AvaMFonts(buffer,number_bytes,types) 

buffer, number_bytes, types: iexp 

Stores the number of fonts (in memory or on disk) to AvailFontsHeader struc¬ 
ture. One AvailFont structure per character set Return value: 0=enror. The ac¬ 
tual error can be inquired with IoErrO. 

buffer address of the memory area for structures. 

number_bytes: block size in bytes. 

types: AFF_MEMORY(l) or AFF_DISK(2) 

CloseFont(textFont) 

textFont: iexp 

This function closes a character set opened with OpenFont or OpenDiskFont. 
textFont: address of the TextFont structure. 

OpenDiskFont(textattr) 

textattr: iexp 

Loads from disk the character set specified in the TextAttr structure. Return 
value: address of the character set TextFont structure. 

textattr address of a TextAttr structure for the character set. 
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OpenFont(textattr) 

textattr: iexp 

Loads a memory resident font (ROM-font) into the TextFont structure. Return 
address: address of the character set TextFont structure. 

textattr address of a TextAttr structure for the character set. 

RemFont(textfont) 

textfont: iexp 

Deletes a character set from the character set list so that is no longer available 
to any program. Return value: 0=no error 
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AttemptLockLayerRom(layer) 

layer: iexp 

This function suspends a Layer for other tasks. Return value: TRUE or 
FALSE. 

layer: address of the Layer structure 

BegfnUpdate(layer) 

layer: iexp 

This function prepares the system for the update of a Layer, 
layer: address of the Layer structure 

BehlndLayer(layerlnfo,layer) 

layerlnfo, layer: iexp 

The Layer is set behind all other Layers. Return value: TRUE or FALSE. 

layerlnfo: address of the Layerlnfo structure 

layer: address of the Layer structure 

CreateBehindLayer(layerlnfo,bitMap,xO,yO,xl,y1,flags,[bitMap2]) 

layerlnfo, bitMap, [bitMap2]:iexp 
xO, yO, xl, y 1, flags:iexp 

Creates a new Layer and sets it behind all other Layers. Return value: address 
of the Layer structure. 

layerlnfo: address of the Layerlnfo structure 

bitMap: address of the BitMap structure. 

xO.yO: coordinates of the upper left comer, 

xl.yl: coordinates of the lower right comer, 

flags: Layer type. 

[bitMap2]: address of an optional Superbitmap. 
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CreateUpfrontLayer(layerln{o,bitMap,xO,yO,xl,y1 .flags, [bitMap2]) 

layerlnfo, bitMap, [bitMap2]:iexp 
xO, yO, xl, yl, flags:iexp 

Creates a new Layer and displays it in from of all other Layers. Return value: 
address of the Layer structure. 

layerlnfo: address of the Layerlnfo structure 

bitMap: address of the BitMap structure. 

xO.yO: coordinates of the upper left comer, 

x 1 ,y 1: coordinates of the lower right comer, 

flags: Layer type. 

[bitMap2]: address of an optional Superbitmap. 

DeleteLayer(layerlnfo,layer) 

layerlnfo, layer: iexp 

Deletes a layer from a Layer list. No return value. 

layerlnfo: address of the Layerlnfo structure, 

layer: address of the Layer structure. 

DisposeLayerlnfo(layerlnfo) 

layerlnfo: iexp 

Releases the Layerlnfo memory. No return value, 
layerlnfo: address of the Layerlnfo structure. 

EndUpdate(layer.flag) 

layer, flag: iexp 

EndUpdate ends a Simple-Refresh. This function is also called by the End- 
RefreshO- No return value. 

layer: address of the Layer structure, 
flags: Layer flags. 
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FattenLayerlnfo(info) 

info: iexp 

When InitLayer() function is used, additional memory for Layerlnfo structure 
must be reserved with FattenLayerlnfo. No return value. 

info: address of a Layerlnfo structure. 

InitLayers(layerinfo) 

layerinfo: iexp 

Initializes a Layerlnfo structure. This is a function from the old V1.0 operating 
system version. The memory for the structure must be reserved with Alloc- 
MemO. No return value. 

layerlnfo: address of the Layerlnfo structure. 

LockLayer(info,layer) 

info, layer: iexp 

Prevents other programs from accessing the Layer. No return value. 

info: address of the Layerlnfo structure, 
layer: address of the Layer structure. 

LockLayerlnfo(info) 

info: iexp 

This function prevents other programs from accessing the given Layerlnfo 
structure. No return value. 

info: address of the Layerlnfo structure. 
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LockLayerRom(layer) 

layer: iexp 

LockLayerRom prevents other programs from accessing the given Layer. No 
return value. 

layer: address of the Layer structure. 

LockLayers(info) 

Prevents other programs from accessing any layer contained in the given 
Layerlnfo structure. No return value. 

info: address of the Layerlnfo structure. 

MoveLayer(lnfo,layer,deltax.deltay) 

info, layer: iexp 
deltax, deltay: iexp 

Using this function normal Layers can be moved. No return value. 

info: address of the Layerlnfo structure, 

layer: address of the Layer structure, 

deltax.deltay: new coordinates of the Layer, relative to old. 

MoveLayerlnFrontOf(layerl,layer2) 

layerl, Iayer2: iexp 

Using this function the Layers on the current level can be moved at will. 
Return value: TRUE or FALSE. 

layerl: address of the Layers to be moved. 

Iayer2: address of the Layer in from of which the layerl will be inserted. 
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NewLayerlnfo(lnfo) 

info: iexp 

This function reserves memory and initializes a Layerlnfo structure. Return 
value: address of the new Layerlnfo structure. 

info: address of an already existing Layerlnfo structure. 

ScrollLayer(lnfo,layer,deltax,deltay) 

info, layer: iexp 
deltax, deltay: iexp 

This function moves the contents of a Superbitmap Layer. No return value. 

info: address of a Layerlnfo structure, 

layer: address of the Layer structure, 

deltax,deltay: new coordinates relative to old position. 

SizeLayerfinfo.layer.deltax.deltay) 

info, layer: iexp 
deltax, deltay: iexp 

Using this function a Layer can be enlarged or shrunk. No return value. 

info: address of the Layerlnfo structure, 

layer: address of the Layer structure, 

deltax,deltay: new coordinates relative to old position. 

SyncSBItMap(layer) 

layer: iexp 

Copies the contents of a Super Bitmap Layer to a Super Bitmap. No return 
value. 

layer: address of the Layer structure. 
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ThinLayerlnfo(info) 

info: iexp 

This function deletes additional memory blocks of a Layerlnfo structure 
created with FattenLayerO. No return value. 

info: address of the Layerlnfo structure. 

UnlockLayer(layer) 

layer: iexp 

This function enables access to a Layer. No return value, 
layer: address of the Layer structure. 

UnlockLayerlnfo(lnfo) 

info: iexp 

This function enables access to a Layerlnfo structure. No return value, 
info: address of the Layerlnfo structure. 

UnlockLayerRom(layer) 

layer: iexp 

This function enables access to a Layer. No return value, 
layer: address of the Layer structure. 
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UnlockLayers(info) 

info: iexp 

This function enables access to aU Layers overlaid in Layerlnfo structure. No 
return address. 

info: address of the Layerlnfo structure. 

Upfrontlayer(lnfo,layer) 

info, layer: iexp 

This function sets the given Layer in front of all other. No return value. 

info: address of the Layerlnfo structure, 
layer: address of the Layer structure. 

WhichLayer(lnfo,x,y) 

info: iexp 

x, y: iexp 

This function returns the address of the Layer at specified coordinates. Return 
value: address of the Layer structure or 0. 

info: address of the Layerlnfo structure. 
x,y: coordinates within the Layer. 
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Close(filehandle) 

filehandle: iexp 

Closes an input or output file. 

filehandle: address of the FileHandle structure. 

CreateOIr(name) 

name: iexp 

Creates and names a directory within the current directory. If this is not pos¬ 
sible a 0 is returned. The relevant error number can be obtained using the 
IoErrO function. If the operation is successful a shared read lock is created for 
the directory. No return value. 

name: directory name. 

CurrentDir(lock) 

lock: iexp 

CurrentDir makes the present directory current. Return value: address of the 
Lock structure of old directory. 

lock: address of new directory Lock structure. 

DateStamp(adr) 

adriexp 

Returns time and date in AmigaDOS format. 

adr: address of three longwords. First longword contains the number of the 
day. The second longword contains elapsed seconds and the third the 
elapsed milliseconds. 
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Delay(time) 

time: iexp 

Halts the current process for the specified amount of time, 
time: time in 1/50 seconds. 

DeleteFlle(name) 

Deletes a file or a directory. The directory should not contain any files or other 
directories. Return value: TRUE or FALSE. If needed, an error number can be 
obtained from IoErr. 

name: file or directory name. 

DupLock(lock) 

lock: iexp 

This function creates a copy of a shared lock structure and returns its address. 
Return value: address of the copied Lock structure. 

lock: address of the Lock structure. 

Examine(lock,fib) 

lock, fib: iexp 

The Examine function writes file or directory data from a Lock structure into a 
File Info Block. The File Info Block contains the name, size, date of creation 
and file or directory type. Return value: on successful completion -1 is 
returned. Otherwise IoErr can be used to obtain the error number. 

lock: address of the Lock structure. 

fib: address of the FilelnfoBlock structure. 
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Execute(inst ruction, In, out) 

instruction: iexp 
in, out: iexp 

Function Execute enables execution of CLI commands. The prerequisite is that 
the C directory on the boot disk contains the CLI "Run" command. 

instruction: a string with the CLI command, 
in: input file handle, 

out: output file handle. 

Exit(ret) 

ret: iexp 

A program or a process is terminated. If the program was started from CLI, 
Exit ends the program and returns to CLI. If the program was started from the 
Workbench, Exit ends the whole process and frees up memory and stack. 

ret: value, which should be given back. 

ExNext(lock.fib) 

lock, fib: iexp 

ExNext test for all entries within a directory. ExNext must be called once for 
each entry. The function ExamineO returns the first entry in the directory 
before all others can be obtained with ExNext Return value: -1 on successful 
completion. 

lock: address of the Lock structure, 
fib: address of a FilelnfoBlock structure. 
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lnfo(lock,info) 

lock, info: iexp 

Info reads information about all connected floppy and hard disks. The infor¬ 
mation contains the disk size in KBytes, the number of free and allocated 
blocks and the number of Soft_Errors. Return value: TRUE or FALSE. 

lock: address of the Lock structure. 

info: address of the memory block in where the information will be copied to. 
This address must be on a longword boundary. 

Input() 

Returns the FileHandle initialized from the program. Return value: FileHandle 
address. 

loErr() 

Returns the error number of the last 10 error, (see error table in the appendix) 
Return value: error number. 

Islnteractive(handle) 

handle: iexp 

This function confirms whether a file is a disk file. Return value: TRUE or 
FALSE. 

LoadSeg(name) 

name: iexp 

LoadSeg loads a program in memory and breaks it up into code segments. 
Return value: address of segment list in memory. 

name: filename. 
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Lock(name,mode) 

name: iexp 
mode: iexp 

Directories or files can be protected from specified access using Lock. Return 
value: address of the Lock structure. 

name: file or directory name. 

mode: with ACCESS_READ(-2) a shared read lock is created. The read 
access to this file is then possible from several programs. With 
ACCESS_WRITE(-1) a write lock is created. The write access is 
then only possible from this program. 

Open(name.mode) 

name: iexp 
mode: iexp 

Opens a file for reading or writing and returns the file handle. Return value: 
file handle. 

name: name of file to access. 

mode: With MODE_OLDFILE(1005) an existing file is opened for 

reading or writing. With MODE_NEWFILE(1006) a new file is 
created and opened for writing. If the file with the same name 
already exists it will be overwritten. 

OutputQ 

Output returns the address of file handle for current output level. Return value: 
address of the FileHandle structure. 


System routines 


11 


89 




DOS-Library 


ParentDlr(lock) 

ParentDir returns the parent directory of a file or a directory. Return value: ad¬ 
dress of a Lock structure. The name of the directory can be read with function 
Examine(). 

lock: address of the Lock structure. 

Read(filehandle,adr,count) 

filehandle, adr, count: iexp 

Reads data from an opened file. Return value: number of bytes read in. 

filehandle: address of the FileHandle structure. 

adr: address of memory buffer where the data is to be read into. 

count: number of bytes to read. 

Rename(old,new) 

old, new: iexp 

Files or directories can be renamed using this function. Return value: TRUE or 
FALSE. 

old: old file name, 
new: new file name. 

Seek(fllehandle,pos,mode) 

filehandle, mode: iexp 
pos: iexp 

This function will position the file pointer to any position within a file. Return 
value: old pointer position. 
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filehandle: address of the FileHandle structure. 

pos: new position of the file pointer (absolute or relative) 

mode: OFFSET_BEGINN(l) set to file start. 

OFFSETJEND(-l) set to end of file. 

OFFSET_CURRENT (0) set to current position. 

SetComment(name,comment) 

name, comment: iexp 

Writes a file specific comment to the directory of the disk. Return value: 
TRUE or FALSE. 

name: file name. 

comment: up to 80 characters of comments. 

SetProtection( name,mode) 

name: iexp 
mode: iexp 

Protects a file or a directory. Return value: TRUE or FALSE, 
name: filename. 

mode: 32 bit value, only the low 4 bits are used: 
bit 3 - read protection, 
bit 2 - write protection, 
bit 1 - executable bit. 
bit 0 - delete protection. 

UnLoadSeg(segment) 

segment: iexp 

Deletes a program (loaded with LoadSeg) from memory. No return value, 
segment: address of the segment list 
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UnLock(lock) 

lock: iexp 

Enables access to a file. No return value, 
lock: address of the Lock structure. 

WaitForChar(filehandle,tlme) 

filehandle, time: iexp 

Tests if a character can be obtained from a file within the specified time. 
Return value: TRUE or FALSE. 

filehandle: address of the FileHandle structure, 

time: amount of time to wait for the character. 

Write(fllehandle, data, length) 

filehandle, data: iexp 
length: iexp 

Wites data to an opened file. Return value: the number of bytes written out. 

filehandle: address of the FileHandle structure, 
data: address of memory with data to write out. 

length: length of data in memory. 
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Keyboard scancodes 


12-2 


GFA-BASIC 3.0 Amiga 



ASCII table 



§ 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 


2 


j 

M 

II 

$ 

7, 

8 

1 

< 

) 

X 

t 

1 


■ 


3 

8 

i 

2 

3 

4 

5 

6 

7 

8 

9 

■ 

• 

i 

1 

< 


D 


4 

8 

A 

B 

C 

D 

E 

F 

G 

H 

I 

J 

X 

L 


a 


5 

P 

« 

R 

S 

I 

11 

V 

U 

X 

Y 

Z 

[ 

\ 


a 


6 

\ 

a 

b 

c 

d 

e 

f 

8 

h 

i 

j 

k 

1 


a 


7 

P 

4 

p 

s 

t 

u 

V 

V 

X 

V 

z 

{ 

1 

> 

M 

1 


A 


i 

« 

t 

» 

Y 

1 

1 

§ 

•• 

§ 

a 

« 


B 

B 

B 

B 

0 

4 

2 

j 

i 

U 

1 

• 

i 

i 

0 

» 


□ 

B 

B 

C 

A 

A 

A 

A 

A 

A 

A 

9 

i 

i 

t 

E 

i 

B 

1 

B 

Q 

B 

a 

& 

6 

6 

3 

a 

a 

0 

a 

a 

a 

a 

B 


B 

E 

i 

i 

i 

1 

a 

3 

2 

5 

3 

3 

8 

a 

n 

B 

B 

B 

F 

S 


5 

6 

8 

3 

1 

a 

0 

il 

G 

& 

a 

B 

}_ 

B 


Appendices 


12-3 






























Special ASCII codes 


a o u e i 

228 246 252 235 239 

A 6 0 E I 

196 214 220 203 207 

\ \ A A \ 

a o u e i 

224 242 249 232 236 

\ \ \ \ 

A O U E I 

192 210 217 200 204 

r 

r r r r m 

a o u e I 

225 243 250 233 237 

r r r r r 

A O U E I 

193 211 218 201 205 


12-4 


GFA-BASIC 3.0 Amiga 






Special ASCII codes 


a o u e i 

226 244 251 234 238 

A A A A A 

A O U E I 

194 212 229 202 205 

r+t /v 

3 6 A O 

227 245 195 213 

8 ? Q 

223 231 199 
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Fill patterns 



These patterns can be used with the command DEFFTLL. The first number sets 
the style and the second number sets the pattern. 
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AmigaDOS error messages 


103 insufficient free store 

104 task table full 

120 argument line invalid or too long 

121 file is not object module 

122 invalid resident library during load 

202 object in use 

203 object already exists 

204 dirctory not found 

205 object not found 

206 invalid window 

209 packet request type unknown 

210 invalid file name 

211 invalid object lock 

212 object type mismatch 

213 disk not validated 

214 disk write protected 

215 cannot rename 

216 directory not empty 

218 device not mounted 

219 seek error 

220 comment to big 

221 disk full 

222 file is protected from deletion 

223 file is protected from writing 

224 file is protected from rerading 

225 not a DOS-disk 

226 no disk in drive 

232 no more directory entries 
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$. 

.$. 

.7-49 

» 

» 

.7-35 

* 

* 

.2-33,2-34 

+. 


. . . .3-10 

=. 

.=. 

.3-11,3-12 

— 

_ 

.3-13 

@ . 

.@ . 

.7-24 

DosBase. 


.10-4 

dosCmdS. 


.10-2 

GfxBase . 


.104 

IntBase. 


.104 

LayersBase. 


.104 

U . 

.U . 

.2-37 

~. 

. ~ . 

.240 

- . 

— . 

.3-10 


ABSO.absO 

ABSOLUTE .ab . 

ACOSOacosO.acosO 

ADD.add 

ADDO.addO 

AFTER .af . 

ALERT ..a 

AND.and 

ANDO.> . .andO 

ARRAYFELL.arr . 

ARRPTRO .anptrO 

ASCO.ascO . 

ASINO .asinO 

ATNQ.atnQ . 


4-12 

2-39 

4-5 

4-2 

4-3 

7-32 

9-36 

3- 5 
4-23 
2-12 
2-33 
2-13 

4- 5 
4-5 


BACKS .ba .9-20 

BACKW .ba ..9-32 

BCHGO.bchgO.4-19 

BGET.bg .6-12 
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BIN$0.bin$0 

BLCRO .blcr() 

BLOAD.bl . 

BMOVE.b . . 

BOUNDARY.bou 

BOX.bo . 

BPUT . ..bp . 

BSAVE .bs . 

BSETO .bsetO 

BTSTO .btstO 

BYTEO .byteO 

BYTE{).byte{} 


2-14 
4-19 
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, 8-5 
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4-19 
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4-26 
2-37 


C: .c: 

CASE.case . 

CARD{} .card{) 

CFLOATO .cfloatO 

CHAIN .chai . 

CHAR{} .char{} 

CHDIR .chd . 

CHRSO .chr$0 

CINTO .cint() . 

CIRCLE.ci 

CLEAR .cle . . 

CLEARW.clearw 

CLIP.cli . . 

CLOSE .cl 

CLOSES .closes 

CLOSEW.closew 

CLS.els . . 

COLLISION ON/OFF/STOP. 

COLOR.c 

COSO.cosO • 
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CVDO .... 


.cvdO. 

. 2-18 

cvio .... 


.cviO. 

. 2-18 

CVLO .... 


.cvlO. 

. 2-18 

cvso .... 


.cvsO. 

. 2-18 

DATA .... 


.d. 

. 5-15 

DATES . . . 


.dateS. 

.2-26 

DEC. 


.dec. 

. 4-10 

DEFBIT . . . 


.defbi. 

. 2-5 

DEFBYT . . 



. 2-5 

DEFFILL . . 


.deffill . 

. 8-3 

DEFFLT . . . 


.defll. 

. 2-5 

DEFFN . . . 


.deffn. 

. 7-26 

DEFINT . . . 


.defi . 

. 2-5 

DEFLINE . . 


.de . 

. 8-6 

DEFNUM . . 


.defn . 

. 5-12 

DEFSTR . . 


.defs . 

. 2-5 

DEFWRD . . 



. 2-5 

DEGO .... 
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. 4-7 
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.dela . 

. 7-37 

DELETE . . 


.del. 
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DFREEO . . 
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DIM. 
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.2-9 
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......... 
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DIR . 


.dir. 

.6-6 

DIR$0 •••• 


.dir$0 . 

.64 

DISPLAY . . 


.display. 

. 8-24 

DIV . 


.div. 

. 4-2 

DIVO .... 


.divO. 

. 4-3 

DO. 


.do . 

. 7-17 

DO UNTIL . 


.do u . 

. 7-18 

DO WHILE . 



. 7-18 

DOUBLE{} . 


.double!) . 

. 2-37 

DOWNTO . . 


.downto . 

. 7-13 

DPEEKQ . . 


.dpeekQ . 

.2-36 
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DPOKE.dp.2-35 

DRAW .dr .8-10,8-12 

DUMP.du .2-31 


EDIT .ed . 

ELLIPSE .ell . 

ELSE .e 

ELSE IF con .e con 

END ..end 

ENDFUNC .endf 

ENDIF.en . 

EOF0 .eofO 

EQV.eqv 

EQVO.eqvO 

ERASE .era . 

ERR.err . 

ERROR.err . 

EVENO.evenO 

EVERY .ev . 

EXEC.exe . 

EXISTO.exist() 

EXIT IF.ex . 

EXPO .expO 
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FRONTS .fronts .9-20 

FRONTW.fr.9-32 

FULLW ..ful.9-32 

FUNCTION.fu .7-24 


GET.ge .6-21,8-22 

GOSUB.g.7-21 

GOTO.got.7-36 

GRAPHMODE.gr .8-7 


HARDCOPY .h.5-20 

HEX$0 .hex$0.2-14 

HTAB.ht .5-13 


IF . . . 
IMP . . 
IMPO . 
INKEY$ 
INLINE 
INPO . 
INPUT . 
INPUTSO 
INSERT 
INSTRO 
INTO • 
INT{) . 


imp . 
impO 
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ini . . 

inpO • 

inp . . 
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intO • 

int(} . 
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KILL 


k 


6-11 


LEFTSO.leftSO 

LENSO .len$0 

LET.le 

LIMITW .lim . . 

LINE .li 

LINE INPUT .li input 

LIST.li . . . 


4-27 

4-34 

2-6 

9-33 

8-10 

5-5 

7-42 
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LUST .... 
LOAD .... 
LOCO 

LOCAL ... 
LOCATE . . 
LOFO .... 
LOGO ... 
LOG100 . . 
LONGO . . 
LOOP .... 
LOOP UNTIL 
LOOP WHILE 
LPEEKO . . 
LPOKE . . . 
LPOSO . . . 
LPRINT . . . 
LSET .... 


11 . . . 
loa . . 
locO • 
loc . . 
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lofO • 
logO • 
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1 . . . 
lu . . 
lw . . 
IpeekO 
lp . . 

lposO 
lpr . . 
Is . . . 


7-42 

7-40 

6-9 

7-23 

5- 7 

6- 9 
4-9 
4-9 

2-37 

7-17 

7-18 

7-18 

2-36 

2-35 

5-19 

5-19 

4-36 


MALLOCO 
MAXO .. 
MENU . . . 
MENU KILL 
MFREEO 
MID$0 . . 
MINO . . . 
MKD$0 . . 
MKI$0 . . 
MKLSO • • 
MKS$0 . . 
MODO . . 
MODE... 
MONITOR 
MOUSE . . 
MOUSEK . 
MOUSEX . 
MOUSEY . 


mallocO . . . . 

.2-41 

maxO . 

.4-16 

me. 

.9-4,9-12 

me kill. 

.9-12 

mfreeO . . . . 

.2-41 

mid$0. 

.... 4-28-4-29 

minO . 

.4-16 

mkd$0 • • • • 

.2-18 

mki$0. 

.2-18 

mkl$0. 

.2-18 

mks$0. 

.2-18 

modO . 

.4-3 

mod. 

.5-11 

m . 

.7-53 

mouse. 

.. .5-17 

mousek . . . . 

.5-17 

mousex . . . . 

.5-17 

mousey . . . . 

.5-17 
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MOVES.moves.9-21 

MOVEW .mov .9-33 

MULQ.mulO .4-3 


NAME 
NC . . 
NEW 
NEXT 
NOT . 


na . 

.6-11 

inc. 

.4-10 

new . 

.7-39 

n. 

.7-13 

not. 

.34 


OBJECT.AX .0. 

OBJECT.AY .o.ay . 

OBJECT.CLIP .o.c. 

OBJECT.CLOSE.o.cl . 

OBJECT.OFF.o.o. 

OBJECT.ON .o.on. 

OBJECT.PLANES .o.p. 

OBJECT.PRIORITY .o.pr . 

OBJECT.SHAPE.o.s. 

OBJECT.START .o.st. 

OBJECT.STOP.o.sto. 

OBJECT.VX .o.v. 

OBJECT.VY .o.vy. 

OBJECT.X .o.x. 

OBJECT.Y .o.y. 

OCT$0 .octSO .... 

ODDO.oddO. 

ON BREAK CONT.on break cont 

ON BREAK GOSUB.on break . . . 

ON COLLISION GOSUB .on collision . 

ON ERROR.on error . . . 

ON ERROR GOSUB.on error . . . 

ON MENU .on menu . . . 

ON MENU BUTTON GOSUB.on menu button 

ON MENU GOSUB .on menu gosub 

ON MENU KEY GOSUB .on menu key 


10-14 
10-14 
10-14 
10-14 
10-15 
10-15 
10-15 
10-15 
10-15 
10-16 
10-16 
10-16 
10-16 
10-16 
10-16 
.2-14 
.4-15 
.7-28 
.7-28 
10-16 
.7-29 
.7-29 
. 9-9 
.9-10 
.9-10 
.9-10 
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Page 

ON MESSAGE GOSUB . . . . 


.9-10 

ON x GOSUB. 

.on x. 

.7-8 

OPEN. 


.6-8 

OPENS . 


.9-17 

OPENW. 

.openw .... 

.9-26 

OPTION BASE. 

.opt base . . . 

.2-10 

OR. 

.or . 

.3-6 

ORO. 

.... .orQ ..... 

.4-23 

OUT. 

.ou. 

.6-13 

PAUSE . 

.pa . 

.7-37 

PBOX. 

.Pb. 

.8-15 

PCIRCLE. 

.pc . 

.8-16 

PEEKO . 

.peekO .... 

.2-36 

PELLIPSE. 

.pe . 

.8-16 

PI . 

.P> . 

.2-25 

PLOT . 

.Pi . 

.8-10 

POINTO. 

.pointO .... 

.8-18 

POKE. 

.po . 

.2-35 

POLYFILL . 

.polyf. 

.8-17 

POLYLINE. 

.pol. 

.8-17 

POSO . 

.posO. 

.5-13 

PREDO . 

.predO .... 

.4-11,4-33 

PRINT. 

.P. 

.5-7 

PRINT#. 

.P#. 

.6-16 

PRINT AT. 

.p at . 

.5-7,5-9 

PRINT USING . 

.p using . . . . 

.5-9 

PROCEDURE . 

.pro. 

.7-21 

PSAVE . 

.PS . 

.7-41 

PUT. 

.Pu. 

.6-21,8-22 

QSORT . 

.qs . 

.2-22 

QUIT . 

.q. 

.7-45 

RADO. 

.radO. 

.4-7 

RANDO . 

.randO .... 

.4-17 
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RANDOMO • • 
RANDOMIZE 
RASTPORT . . 
RCALL .... 

READ. 

RECALL . . . 
RECORD . . . 
RELSEEK . . . 

REM. 

RENAME . . . 
REPEAT .... 
RESERVE . . . 
RESTORE . . . 
RESUME NEXT 
RETURN . . . 
RIGHTSO . . . 
RINSTRO . . . 

RND. 

RORO. 

ROUNDO . . . 

RSET . 

RUN. 


. random 0 . . . 

.4-17 

.ra . 

.4-17 

.ras. 

.8-8 

.rc . 

.7-55 

.rea. 

.5-15 

.reca . 

.6-17 

.rec. 

.6-21 

.rel. 

.6-19 

.r. 

.7-35 

.ren. 

.6-11 

.rep. 

.7-15 

.rese .. 

.2-44 

.res. 

.5-15 

.resu next .... 

.7-29 

.ret. 

.7-21,7-24 

.right$0 .... 

.4-27 

.rinstrO. 

.4-31 

md. 

.4-17 

rorO. 

.4-22 

roundO .... 

.4-14 

rs . 

.4-36 

ru . 

.7-44 


SAVE .sa 

SAY.say . . 

SCREENO .screenO 

SEEK .see 

SELECT.s ... 

SETCOLOR.set 

SETDRAW.setd . 

SETPEN.sets 

SETSTITLE.setst . 

SETTIME.sett . . 

SETWPEN .setwp 

SETWTITLE .setwt . 

SGNO.sgnQ . 


.7-41 
.10-9 
.9-24 
.6-19 
. 7-9 
. 8-2 
. 8-12 
.9-23 
.9-23 
2-27 
9-34 
9-34 
4-12 
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SHLO . . 
SHRO . . 
SINO . . 
SINGLE{} 
SINQO . 
SIZEW . 
SLEEP . . 
SOUND . 
SPACES!) 
SPCO . . 
SPRITE . 
SQRO . • 
STICK . . 
STOP . . 
STORE . 
STR$0 . 
STRIG . . 
STRINGS!) 
SUB . . . 
SUBO . . 

succo • 

SWAP . . 
SWAPO . 
SYSTEM 


shlO. 

.4-21 

shrO. 

.4-21 

sinO. 

.4-5 

single!} . . . . 

.2-37 

sinqO . 

.4-6 

siz. 

.9-33 

sle. 

.9-9 

so . 

.5-22 

spaceSO .... 

.4-32 

spcO. 

.4-32 

spr. 

.10-5 

sqrO. 

.4-8 

sti . 

.10-7 

st. 

.7-38 

stor . 

.6-17 

str$0. 

.2-15 

strig. 

.10-7 

stringSO .... 

.4-32 

sub. 

.4-2 

subO. 

.4-3 

succO . 

.4-11,4-33 

sw. 

.2-20 

swapO. 

.4-25 

sy . 

.7-45 


TABO. 

TANO. 

TEXT. 

TIMES. 

TIMER .... 
TITLES .... 
TITLEW . . . 
TOUCH .... 
TRACES . . . 
TRANSLATES!) 
TRIMSO 


tabO.5-13 

,tan().4-5 

t.8-21 

,time$ .2-26 

.timer.2-28 

titles.9-22 

ti.9-32 

.tou.6-9 

.traceS .7-48 

■translates!) .10-9 

,trim$0.4-34 
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TROFF .troff.7-46 

TRON.tr.7-46,7-48 

TRUE.true .2-25 

TRUNCO.truncO.4-13 

TYPEO .typeO .2-30 


UNTIL .u.7-15 

UPPER$0.upper$0.4-35 


V: . 


VALO. 

.valO • 

VAL?0 . 

.val?0 

VARPTRO . 

.varptrO 

VOID . 


VSYNC . 

.vs 

VTAB. 

.vt . . 


2-33 

2-16 

2-16 

2-33 

2-40 

8-23 

5-13 


WAVE . . . 
WEND . . 
WHILE . . 
WINDOWO 
WORDO . 
WORDO . 
WRITE . . 
WRITE# . 


,wa.5-22 

.we.7-16 

.w .7-16 

windowO .9-35 

.woidO.4-26 

,word(} .2-37 

wr.5-7 

wr#.6-16 


XOR.xor.3-7 

XORO.xorQ.4-23 
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AbortlO.11-3 

ActivateGadget.11-58 

Activate Window .11-58 

AddAnimOb .11-24 

AddBop.11-24 

AddDevice .11-3 

AddFont.11-24 

AddFreeList. 11-3 

AddGadget .11-58 

AddGList .11-58 

AddHead .11-3 

AddlntServer .11-4 

AddLibrary .11-4 

AddPort.114 

AddResource .114 

AddTail .11-5 

AddTask.11-5 

AddVSprite.11-24 

Allocate.11-5 

AllocEntry .11-5 

AllocMem.11-6 

AllocRaster.11-25 

AllocRemember.11-59 

AllocSignal .11-6 

AllocTrap.11-6 

AllocWBObject.11-25 

AlohaWorkbench .11-59 

AndRectRegion.11-25 

AndRegionRegion .11-25 

Animate.11-25 

AreaCircle.11-26 

AreaDraw.11-26 

AreaEllipse .11-26 

AreaEnd.11-27 

AreaMove.11-27 

AskFont.11-27 
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AskSoftStyle .11-27 

AttemptLockLayerRom.11-78 

AutoRequest .11-59 

AvailFonts.11-76 

AvailMem.11-6 

BeginRefresh .11-60 

BeginUpdate .11-78 

BehindLayer .11-78 

BltBitMap.11-28 

BltBitMapRastPort.11-28 

BltClear.11-29 

BltMaskBitMapRastPort.-.11-29 

BltPattem .11-30 

BltTemplate.11-30 

BuildSysRequest .11-60 

BumpRevision .11-54 

Cause . 11-7 

ChangeSprite .11-30 

ClearDMRequest .11-60 

ClearEOL.11-31 

ClearMenuStrip.11-61 

ClearPointer.11-61 

ClearRectRegion .11-31 

ClearRegion.11-31 

ClearScreen.11-61 

ClipBlit .11-31 

Close .11-85 

CloseDevice.11-7 

CloseFont.11-76 

CloseLibrary .11-7 

CloseScreen.11-61 

CloseWindow.11-61 

CloseWorkBench .11-54 

CopySBilMap.11-32 
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CreateBehindLayer 

CreateDir . 

CreateExtIO . . . . 
CreateProc .... 
CreateStdIO . . . . 
CreateUpfrontLayer 

CurrentDir. 

CurrentTime . . . . 
CWait. 


11-78 

11-85 

.11-8 

.11-8 

.11-8 

11-79 

11-85 

11-62 

11-32 


DateStamp .11-85 

Deallocate.11-7 

Debug.11-8 

Delay .11-86 

DeleteFile.11-86 

DeleteLayer.11-79 

DeviceProc .11-9 

Disable .11-9 

DisownBlitter.11-32 

Display Alert.11-62 

DisplayBeep.11-62 

DisposeLayerlnfo.11-79 

DisposeRegion .11-32 

DoCollision.11-33 

DoIO .11-9 

Doubleclick.11-62 

Draw .11-33 

DrawBorder.11-63 

DrawCircle .11-33 

DrawEllipse.11-33 

DrawGList .11-34 

Drawlmage .11-63 

DupLock .11-86 

Enable.11-9 

EndRefiesh .11-63 
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EndRequest.11-64 

EndUpdate .11-79 

Enqueue.11-9 

Examine.11-86 

Execute .11-87 

Exit .11-87 

ExNext .11-87 

FattenLayerlnfo.11-80 

FindName.11-10 

FindPort.11-10 

FindResident .11-10 

FindTask . r .11-10 

FindToolTypes .11-54 

Hood .11-34 

Forbid.11-11 

FreeColorMap.11-34 

FreeCopList.11-35 

FreeCprList.11-35 

FreeDiskObject.11-54 

FreeEntry .11-11 

FreeFreeList.11-11 

FreeGBuffers .11-35 

FreeMem .11-11 

FreeRaster.11-11 

FreeRemember .11-64 

FreeSignal.11-12 

FreeSprite.11-35 

FreeS ysRequest.11-64 

FreeTrap.11-12 

FreeVPortCopLists.11-36 

FreeWBObject .11-55 

GetCC.11-12 

GetColorMap.11-36 

GetDefPrefs.11-65 
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GetDiskObject .11-55 

GetGBuffers.11-36 

Getlcon .11-55 

GetMsg .11-12 

GetPrefs.11-65 

GetRGB4 .11-36 

GetScreenData .11-37 

GetSprite .11-37 

GetWBObject.11-55 

Info .11-88 

InitArea.11-38 

InitBitMap .11-38 

InitCode.11-13 

InitGels .11-38 

InitGMasks .11-39 

InitLayers.11-80 

InitMasks .11-39 

InitRastPort.11-39 

InitRequester .11-65 

InitResident.11-13 

InitStruct .11-13 

InitTmpRas.11-39 

InitView.11-40 

InitVPort .11-40 

Input.11-88 

Insert .11-13 

InstallClipRegion.11-40 

IntuiTextLength.11-65 

Intuition.11-66 

IoErr.11-88 

Islnteractive.11-88 

Item Address.11-66 

LoadRGB4 .11-40 

LoadSeg.11-88 
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LoadView.11-41 

Lock.11-89 

LockIBase.11-41 

LockLayer.11-80 

LockLayerlnfo .11-80 

LockLayerRom.11-81 

LockLayers .11-81 

MakeLibrary .11-14 

MakeScreen.11-66 

MakeVPort .11-41 

MatchTool Value .11-56 

MenuNum.1142 

ModifyIDCMP .11-66 

ModifyProp.11-67 

Move .1142 

MoveLayer .11-81 

MoveLayerlnFrontOf.11-81 

MoveScreen.11-67 

MoveSprite .1142 

MoveWindow.11-67 

MrgCop.1142 


NewLayerInfo.11-82 

NewRegion.1143 


OfTGadget.11-68 

OffMenu .11-68 

OnGadget.11-68 

OnMenu.11-69 

Open.. . ; . . 11-89 

OpenDevice.11-14 

OpenDiskFont.11-76 

OpenFont .11-77 

OpenLibrary.11-15 

OpenResource.11-15 
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OpenScreen.11-69 

Open Window.11-69 

OpenWorkBench .11-56 

OrRectRegion.11-43 

OrRegionRegion .11-43 

Output.11-89 

OwnBlitter .11-43 

ParentDir .11-90 

Permit.11-15 

Poly Draw .11-43 

PrintIText.11-69 

Procure .11-15 

PutDiskObject.11-56 

Putlcon .11-56 

PutMsg .11-16 

PutWBObject.11-57 

QBlit .11-44 

QBSBlit.11-44 

RasSize .11-44 

RawDoFmt .11-16 

RawKeyConvert .11-16 

Read.11-90 

ReadPixel.11-44 

RectFill .11-45 

RefreshGadgets.11-70 

RefreshGList .11-70 

RefreshWindowFrame .11-71 

RemakeDisplay.11-71 

RemDevice .11-17 

RemFont .11-77 

RemHead .11-17 

RemIBob .11-45 

RemLibrary.,.11-17 
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Remove.11-17 

RemoveGadget.11-71 

RemoveGList.11-71 

RemPort.11-18 

RemResource.11-18 

RemTail.11-18 

RemTask .11-18 

RemVSprite.11-45 

Rename .11-90 

ReplyMsg.11-19 

ReportMouse .11-46 

Request .11-71 

RethinkDisplay.11-72 

ScreenToBack.11-72 

ScreenToFront .11-72 

ScrollLayer .11-82 

ScrollRaster.11-46 

ScrollVPort .11-46 

Seek.11-90 

SendIO .11-19 

SetAfPt .11-46 

SetAPen.11-47 

SetBPen.11-47 

SetCollision.11-47 

SetComment .11-91 

SetDMRequest .11-72 

SetDrMd .11-48 

SetDrPt .11-48 

SetExept.11-19 

SetFont . 11-48 

SetFunction.11-19 

Setlnt Vector.11-20 

SetMenuStrip.11-72 

SetOPen.11-48 

SetPointer.11-73 
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SetPrefs.11-73 

SetProtection .11-91 

SetRast .11-49 

SetRGB4 .11-49 

SetRGB4CM .11-49 

SetSignal .11-20 

SetSoftStyle.1M9 

SetSr.11-20 

SetTaskPri.11-20 

SetWindowTitles .11-73 

SetWrMsk . ..11-21 

Shiftltem .11-74 

ShiftMenu.11-74 

ShowTitle.11-74 

Signal .11-21 

SizeLayer.11-82 

SizeWindow.11-74 

SortGList .11-50 

SumLibrary.11-21 

Superstate.11-21 

SwapBitsRastPortClipRect.11-21 

SyncSBitMap.11-82 

Text.11-50 

TextLength .11-50 

ThinLayerlnfo.11-83 

Translate.11-51 

UCopperListlnit.11-51 

UnLoadSeg.11-91 

UnLock .11-92 

UnlockIBase .11-75 

UnlockLayer .11-83 

UnlockLayerlnfo .11-83 

UnlockLayerRom.11-83 

UnlockLayers.11-84 
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Upfrontlayer.11-84 

UserState .11-22 

Vacate.11-22 

VBeamPos .11-51 

View Address .11-51 

ViewPortAddress.11-52 

Wait.11-22 

WaitBlit.11-52 

WaitBOVP .11-52 

WaitForChar .11-92 

WaitIO.11-22 

WaitPort. 11-23 

WBenchToBack.11-57 

WBenchToFront .11-57 

WhichLayer.11-84 

WindowLimits .11-75 

WindowToBack.11-75 

WindowToFront.11-75 

Write .11-92 

WritePixel.11-52 

XorRectRegion .11-52 

XorRegionRegion.11-53 
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Chapter 13 

New features in GFA Basic 3.5 


New Editor features in GFA Basic 3.5 

1. The editor uses two more bytes per program row than the old 
editor (Versions 3.0 to 3.07). This accelerates the “backward scrolling” 
and makes it possible to fold functions, too. 

2. You can now also use the “Search” function to search in the 
header rows of closed procedures or functions. 

3. Listing now prints “labels” two characters to the left (as with CASE). 


Tab functions 


Tab 

Ctrl+Tab 

LeftShift+Tab 

RightShift+Tab 


Cursor jumps to next tabulator position. 

Cursor jumps the last previous tab position. 

Inserts blank spaces to the next tab position. 

Deletes all blank spaces in one row up to or from 
cursor. 


Linear operations with vectors and matrix 

All functions described in this chapter relate only to one and/or 
two-dimensional fields with floating point variables. 

System commands 

MAT BASE 0 
MAT BASE 1 

The MAT BASE command can only sensibly be used when OPTION 
BASE 0 has been activated. In this case, MAT BASE 1 can be used to 
set the offset for the start of the row and column indexing of one or 
two-dimensional fields with floating point variables to 1 for the matrix 
operations. MAT BASE 0 resets this offset to 0 after a MAT BASE 1. 

Abbreviation: m b 0/m b 1 


Basic 3.5 New Commands 
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The setting made with MAT BASE n affects the following commands 

MAT READ 
MAT PRINT 
MAT CPY 
MAT XCPY 
MAT ADD 

MAT SUB MAT MUL 

The default is MAT BASE 1. 

Example: 

OPTION BASE 0 
MAT BASE 1 

DATA 1,2,3,4,5,6,7,8,9.10,11,12,13,14,15,16 
DIM a(3,3) 

MAT READ a() 

PRINT a(1,1) 

Outputs value of 1 

Generating commands 

MAT CLR a() 

MAT SET a()=x 
MAT ONE a() 

a: Name of field with numeric variables 
x: aexp 

MAT CLR a() corresponds to an ARRAYFILL a(),0, i.e. the command 
sets all elements in the field (matrix or vector) a() to a value of 0. 

Abbreviation: m cl a() 

MAT SET a()=x corresponds to an ARRAYFILL a(),x, i.e. the command 
sets all elements in the field a() (matrix or vector) to the value x. 

Abbreviation: m se a()=x 

MAT ONE a() generates from a square matrix a() a uniform matrix, i.e. 
a square matrix in which elements a(1,1),a(2,2),...,a(n.n) are all equally 
1 and all other elements equally 0. 

Abbreviation: m o a() 
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Example: 

DATA 1,2,3,4,5,6,7,8,9.10,11,12,13,14,15,16 
DIM a(3,3) 

MAT READ a() 

PRINT a(1,1) 

MAT CLR a() 

PRINT a(1,1) 

Outputs the value 1, then 0. 

DIM a(5,7) 

FOR i%=1 TO 5 
FOR j%=1 TO 7 
a(i%,j%)=RAND(10) 

NEXT j% 

NEXT i% 

MAT SET a(),5.3 
FOR i%=1 TO 5 
FOR j%=1 TO 7 
PRINT a(i%,j%) 

NEXT j% 

NEXT i% 

Outputs the value 3.5 35 times. 

DIM a(3,3) 

MAT ONE a() 

MAT PRINT a() 

Gives 1,0,0 
0 , 1,0 
0 , 0,1 

Write and Read commands 


MAT READ a() 

MAT PRINT [#i]a[,g,n] 

MAT INPUT #i,a() 

i,g,n: iexp 

a: Name of field with numerical variables 


Basic 3.5 New Commands 
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MAT READ a() reads a previously dimensioned matrix or vector from 
DATA rows. 

Abbreviation: m r a() 

Example: 

DATA 1,2,3,4,5,6,7,8,9,10 
DIM a(2,5) 

MAT READ a() 

PRINT a(2,4) 
outputs the value 9. 

MAT PRINT [#i,]a()[,g,n] outputs a matrix or a vector. Vectors are 
output on one row, the elements being separated by commas. With 
matrix, each row is followed by a rowfeed. 

The output can optionally be redirected with #i, as with PRINT. 

If g and n are specified, the numbers are formatted as with 
STR$(x,g,n). 

Abbreviation: m p [#i]a()[g,n] or m ? [#i,]a()[g,n] 

Example: 

DATA 1,2.33333,3 
DATA 7,5.25873,9.376 
DATA 3.23,7.2,8.999 
DIM a(3,3) 

MAT READ a() 

MAT PRINT a<) 

PRINT”-” 

MAT PRINT a(),7,3 

Gives: 1,2.33333,3 

7,5.25873,9.376 

3.23,7.2,8.999 


1.000,2.333,3.000 

7.000,5.259,9.376 

3.230,7.200,8.999 
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MAT INPUT #1,a() reads a matrix or vector from a file in ASCII format 
(the format being the reverse of MAT PRINT, commas and rowfeeds 
may be varied as with INPUT #). 

Abbreviation: m i #i,a(). 

Example: 

OPEN ‘‘o”,#1,"Test.DAT" 

DIM a(3,3) 

MAT ONE a() 

MAT PRINT #l,a() 

CLOSE #1 
MAT CLR a() 

OPEN “i”,#1,"Test.DAT” 

MAT INPUT #l,a() 

CLOSE #1 
MAT PRINT a() 

Gives: 1,0,0 

0 , 1,0 
0 , 0,1 

Copy and Transposition commands 

MAT CPY a([i,j])=b([k,l])[,h,w] 

MAT XCPY a([i,j])=b([k,l])[,h,w] 

MAT TRANS a()[=b()] 

a,b: Name of fields with numerical variables 

i,j,k,l,h,w: iexp 

MAT CPY a([i,j])=b([k,l])[,h,w] copies h rows with w elements each 
from matrix b to the row and column offset of matrix a defined by i,j, 
starting from the row and column offset of matrix b defined by l,k. 
Abbreviation: m c a(i,j)=b(k,l),h,w, 

m x a(i,j)=b(k,l),h,w, 

m t a()=b(). 

Example: 

DIM a(5,5),b(4,4) 

MAT SET a()=1 
FOR i%=1 TO 4 
FOR j%=1 TO 4 
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b(i%,j%)=SUCC(i%) 

NEXT j% 

NEXT i% 

MAT PRINT a() 

PRINT “-” 

MAT PRINT b() 

PRINT “-” 

MAT CPY a(2,2)=b(2,2),3,3 
MAT PRINT a() 

Gives: 1,1,1.1,1 

1 , 1 , 1 , 1,1 

1 , 1 , 1 , 1,1 

1,1,1,1,1 

1,1,1,1,1 


2,2,2,2 

3.3.3.3 

4.4.4.4 

5.5.5.5 


1 , 1 , 1 , 1.1 

1.3.3.3.1 

1.4.4.4.1 

1.5.5.5.1 

1 . 1 . 1 . 1.1 

Special cases 

MAT COPY a()=b() copies the complete matrix b into matrix a if the 
matrix are of the same order. 

Only those elements are copied in this process for which identical 
indices are given in both the source and the destination matrix. 

Abbreviation: m c a()=b(). 

Example: 

DIM a(5,3),b(4,4) 

MAT SET a()=1 
FOR i%=1 TO 4 
FOR j%=1 TO 4 
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b(i%,j%)=SUCC(i%) 
NEXT j% 

NEXT i% 

MAT PRINT a() 

PRINT “- 

MAT PRINT b() 

PRINT “- 

MAT CPY a()=b(),3,3 
MAT PRINT a() 

Gives: 1,1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 


2 , 2 , 2,2 

3.3.3.3 

4.4.4.4 

5.5.5.5 


2 , 2,2 

3.3.3 

4.4.4 
1 , 1,1 
1 , 1,1 

MAT COPY a(i,j)=b() copies matrix b, starting from the row and 
column offset defined by MAT BASE, to the row and column offset of 
matrix a defined by i,j. Only those elements are copied for which 
identical indices are given in both the source and the destination 
matrix. 

Abbreviation m c a(i,j)=b() 

Example 


DIM a(5,3),b(4,4) 
MAT SET a()=1 
FOR i%=1 TO 4 
FOR j%=1 TO 4 
b(i%,j%)=SUCC(i%) 
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NEXT j% 

NEXT i% 

MAT PRINT a() 

PRINT “-” 

MAT PRINT b() 

PRINT “-” 

MAT CPY a(2,2)=b(2,2),3,3 
MAT PRINT a() 

Gives: 1,1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 


2 , 2 , 2,2 

3.3.3.3 

4.4.4.4 

5.5.5.5 


1 , 1,1 

1.3.3 

1.4.4 

1.5.5 

1 , 1,1 

MAT COPY a()=b(i,j) copies matrix b, starting from the row and 
column offset defined by i,j, to the offset of matrix a defined by MAT 
BASE. Only those elements are copied for which identical indices are 
given in both the source and the destination matrix. 

Abbreviation: m c a()=b(i,j). 

Example: 

DIM a(5,3),b(4,4) 

MAT SET a()=1 
FOR i%=1 TO 4 
FOR j%=1 TO 4 
b(i%,j%)=SUCC(i%) 

NEXT j% 

NEXT i% 
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MAT PRINT a() 

PRINT “- 

MAT PRINT b() 

PRINT “- 

MAT CPY a()=b(2,2),3,3 
MAT PRINT a() 

Gives: 1,1,1 

1 . 1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 


2,2,2,2 

3.3.3.3 

4.4.4.4 

5.5.5.5 


3.3.3 

4.4.4 

5.5.5 

1 , 1,1 

1,1,1 

MAT COPY a(i,j)=b(k,l) copies matrix b, starting from the row and 
column offset defined by k,l, to the offset i,j of matrix a. Only those 
elements are copied for which identical indices are given in both the 
source and the destination matrix. 

Abbreviation: m c a(i,j)=b(k,l). 

Example: 

DIM a(5,3),b(4,4) 

MAT SET a()=1 
FOR i%=1 TO 4 
FOR j%=1 TO 4 
b(i%,j%)=SUCC(j%) 

NEXT j% 

NEXT i% 
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MAT PRINT a() 

PRINT “- 

MAT PRINT b() 

PRINT “- 

MAT CPY a(2,2)=b(2,2) 
MAT PRINT a() 

Gives: 1,1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 


2 , 3 , 4,5 
2,3,4,5 
2,3,4,5 
2,3,4,5 


1 , 1,1 

1.3.4 

1.3.4 

1.3.4 

1 , 1,1 

MAT COPY a()»b() copies h rows with w elements each from the 
matrix b, starting from the row and column offset defined by MAT 
BASE, the row and column offset of matrix a defined by MAT BASE. 
Only those elements are copied for which identical indices are given 
in both the source and the destination matrix. 

Abbreviation: m c a()=b(). 

Example: 

DIM a(5,3),b(4,4) 

MAT SET a()=1 
FOR i%=1 TO 4 
FOR j%=1 TO 4 
b(i%,j%)=SUCC(j%) 

NEXT f/o 
NEXT i% 

i 

MAT PRINT a() 

PRINT “-” 
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MAT PRINT b() 

PRINT “- 

MAT CPY a()=b() 
MAT PRINT a() 

Gives: 1,1,1 

1 , 1,1 

1 , 1,1 

1,1,1 

1 , 1,1 


2 , 3 , 4 , 5 
2 , 3 , 4 , 5 
2 , 3 , 4 , 5 
2 , 3 , 4 , 5 


2,3,4 

2,3,4 

2,3,4 

2,3,4 

1 . 1,1 

MAT XCPY a([i,j])=b([k,l])[,h,w] works basically in the same manner as 
MAT CPY a([i,]])=b([k,l])[,h,w], except that matrix b is being trans¬ 
posed while being copied to matrix a, i.e. the rows and columns of 
matrix b are swapped while it is copied to matrix a. Array b remains 
unchanged, however. Only those elements are copied for which 
identical indices are given in both the source and the destination 
matrix. 

Abbreviation: m x a(i,j)=b(k,l),h,w. 

Example: 

DIM a(5,3),b(4,4) 

MAT SET a()=1 
FOR i%-1 TO 4 
FOR j%=1 TO 4 
b(i%,j%)=SUCC(j%) 

NEXT j% 

NEXT i% 

MAT PRINT a() 

PRINT “-” 
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MAT PRINT b() 

PRINT “-” 

MAT XCPY a(2,2)=b{2,2),3,3 
MAT PRINT a() 

Gives: 1,1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 

1 , 1,1 


2 , 3 , 4,5 
2,3,4,5 
2,3,4,5 
2,3,4,5 


1 , 1,1 

1.3.3 

1.4.4 

1.5.5 

1 , 1,1 

Further special cases 

As with MAT CPY a(i,j)=b(k,l),w,h. 

If MAT CPY or MAT XCPY are applied to vectors, j and I may be 
ignored. Following a DIM a(n),b(m), a() and b() are interpreted as row 
vectors, i.e. as matrix of the (1 ,n) or (1 ,m) types. 

For a and b to be treated as column vectors, they must be 
dimensioned as matrix of the (n,l) or (m,l) type, ie. DIM a(n,1),b(n,1). 

If both vectors are of the same order (both are row or column 
vectors), MAT CPY must be used. Irrespective of the type of vectors a 
and b, MAT CPY always treats both vectors syntactically as column 
vectors, so that the correct syntax to be used for MAT CPY is always 

MAT CPY a(n,1)=b(m,1)! 

Example: 

DIM a(10),b(5) ’ a() und b() are row vectors 
MAT SET a()=1 
FOR i%=1 TO 5 
b(i%)=SUCC(i%) 


13-12 


GFA-BASIC 3.5 Amiga 






GFA-BASIC 3.5 Addendum 


NEXT i% 

PRINT “a(): 

MAT PRINT a() 

PRINT “b(): 

MAT PRINT b() 

PRINT STRING$(45,”-”) 

MAT CPY a(3,1)=b(1,1) ! interprets a() and b() as column vectors 
PRINT “MAT CPY a(3,1)=b(1,1): 

MAT PRINT a() 

Gives: a(): 1,1,1,1,1,1,1,1,1.1 

b(): 2,3,4,5,6 

MAT CPY a(3,1)=b(1,1): 1,1,2,3,4,5.6,1,1,1 

For MAT XCPY, one of the two vectors a and b must be explicitly 
dimensioned as a row vector, the other as a column vector: for 
example 

DIM a(1,10),b(5,l), 

since MAT XCPY first transposes the second vector before copying it 
to the first. For this reason, MAT XCPY can only be used for DIM 
a(1,n),b(m,1): a()=row vector, b()=column vector and DIM 
a(n,1),b(1,m): a()=column vector, b()=row vector. 

Example: 


DIM a(1,l0),b(5,1) 

MAT SET a()=1 
FOR i%=1 TO 5 
b(i%,1)=SUCC(i%) 

NEXT i% 

MAT PRINT a() 

PRINT 

MAT PRINT b() 

MAT XCPY a(1,3)=b(1,1) 
PRINT 

MAT PRINT a() 
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Gives: 1,1,1,1,1,1,1,1,1,1 

2 

3 

4 

5 

6 

1 . 1 . 2 . 3 . 4 . 5 . 6 . 1 . 1.1 

Optionally, the parameters h and w can also be used when copying 
vectors with MAT CPV or MAT XCPY. However, the following applies: 
with MAT CPY, only the h parameter is used for w=>l. No copying 
takes place with w=0. 

With MAT XCPY, only h is used for w=>l if b is a column vector to be 
copied into a row vector after transposition. No copying takes place 
when w=0. On the other hand, only w is used for h=>1 if b is a row 
vector which is to be copied to a column vector after transposition. In 
this case, no copying takes place if h=0. 

MAT TRANS a()=b() copies the transposed from matrix b to matrix a if 
a and b are dimensioned accordingly, i.e. the number of rows from a 
must correspond to the number of columns in b, and the number of 
columns from a to the number of rows of n: for example, DIM 
a(n,m),b(m,n). 

Example: 

DIM a(3,4),b(4,3) 

MAT SET b()=4 
MAT SET a()=1 
MAT PRINT a() 

PRINT STRING$(10,"-”) 

MAT PRINT b() 

PRINT STRING$(10,”-”) 

MAT TRANS a()=b() 

MAT PRINT a() 

gives 1,1,1,1 

1 . 1 . 1.1 
1 , 1 , 1,1 


4,4,4 

4,4,4 

4,4,4 
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4,4,4 


4,4,4,4 

4,4,4,4 

4,4,4,4 

In the case of a square matrix, i.e. one with equal numbers of rows 
and columns, MAT TRANS a() may be used. This command swaps the 
rows and columns of matrix a and writes the matrix thus changed 
back to a. 

(The original matrix is lost in the process (but can be restored with 
another MAT TRANS a()). 

Abbreviation: m t a(). 

Example: 

DIM a(5,5) 

FOR i%=1 TO 5 
FOR j%=1 TO 5 
a(i%,j%)=j% 

NEXT j% 

NEXT i% 

MAT PRINT a() 

PRINT STRING$(10,”-”) 

MAT TRANS a() 

MAT PRINT a() 

Gives: 1,2,3,4,5 

1,2,3,4,5 
1,2,3,4,5 
1,2,3,4,5 
1,2,3,4,5 


1 , 1 , 1 , 1,1 
2,2,2,2,2 

3.3.3.3.3 

4.4.4.4.4 

5.5.5.5.5 
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Operation commands 

MAT ADD a()=b()+c() 

MAT ADD a(),b() 

MAT ADD a(),x 
MAT SUB a()=b()-c() 

MAT SUB a(),b() 

MAT SUB a(),x 
MAT MUL a()=b()*c() 

MAT MUL x=a()*b() 

MAT MUL x=a()*b()*c() 

MAT MUL a(),x 
MAT NORM a(),0 
MAT NORM a(),1 
MAT DET x=a([i,j])[,n] 

MAT QDET x=a([i,j])[,n] 

MAT RANG x=a([i,j])[,n] 

MAT INV a()=b() 

a,b,c: Names of numerical floating point fields 
x: aexp; scalar value 
i.j,n: aexp 

MAT ADD a()=b()+c() is only defined for matrix (vectors) of the same 
order, e.g. DIM a(n,m),b(m,m),c(n,m) or DIM a(n),b(n),c(n). Array c is 
added to matrix b, element by element, and the result is written to 
matrix a. 

Abbreviation: m a()=b()+c(). 

Example: 

DIM a(3,5),b(3,5),c(3,5) 

MAT SET b()=3 
MAT SET c()=4 
MAT PRINT b() 

PRINT STRING$(10,”-”) 

MAT PRINT c() 

PRINT STRING$(10,”-”) 

MAT ADD a()=b()+c() 

MAT PRINT a() 
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Gives: 3,3,3,3,3 

3,3,3,3,3 

3,3,3,3,3 


4.4.4.4.4 

4.4.4.4.4 

4,4,4,4,4 


7.7.7.7.7 

7.7.7.7.7 

7,7,7,7,7 

MAT ADD a(),b() is only defined for matrix (vectors) of the same order, 
e.g. DIM a(n,m),b(n.m) or DIM a(n),b(n). Array b is added to matrix a, 
element by element, and the result is written to matrix a. ' 

The original matrix a is lost in the process. 

Abbreviation: m a a(),b(). 

Example: 

DIM a(3,5),b(3,5) 

MAT SET a()=1 
MAT SET b()=3 
MAT PRINT a() 

PRINT STRING$(10,”-”) 

MAT PRINT b() 

PRINT STRING$(10,”-") 

MAT ADD a(),b() 

MAT PRINT a() 

Gives: 1,1,1,1,1 

1 , 1 , 1 , 1,1 
1 , 1 , 1 , 1,1 


3,3,3,3,3 

3,3,3,3,3 

3,3,3,3,3 


4,4,4,4,4 

4,4,4,4,4 

4,4,4,4,4 
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MAT ADD a(),x is defined for all matrix (vectors). Here, the scalar x is 
added to matrix a, element by element, and the result is written to 
matrix a. The original matrix a is lost in the process. 

Abbreviation: m a a(),x. 

Example: 


DIM a(3,5) 

MAT SET a()=1 
MAT PRINT a() 

PRINT STRING$(10,”-") 
MAT ADD a(),5 
MAT PRINT a() 

Gives: 1,1,1,1,1 

1 , 1 , 1 , 1.1 
1 , 1 , 1 , 1,1 


6 , 6 , 6 , 6,6 
6 , 6 , 6 , 6,6 
6 , 6 , 6 , 6,6 

MAT SUB a()=b()+c() is only defined for matrix (vectors) of the same 
order, e.g. DIM a(n,m),b(n,m),c(n,m) or DIM a(n),b(n),c(n). Array c is 
subtracted from matrix b, element by element, and the result is written 
to matrix a. 

Abbreviation: m a()=b()-c(). 

Example: 

DIM a(3,5),b(3,5),c(3,5) 

MAT SET b()=5 
MAT SET c()=3 
MAT PRINT b() 

PRINT STRING$(10,”-”) 

MAT PRINT c() 

PRINT STRING$(10,”-”) 

MAT SUB a()=b()-c() 

MAT PRINT a() 
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Gives: 5,5.5,5,5 

5,5,5,5,5 
5,5,5,5,5 


3,3,3,3,3 

3,3,3,3,3 

3,3,3,3,3 


2,2,2,2,2 

2 , 2 , 2 , 2,2 

2 , 2 , 2 , 2,2 

MAT SUB a(),b() is only defined for matrix (vectors) of the same order, 
e.g. DIM a(n,m),b(n,m) or DIM a(n),b(n). Array b is subtracted from 
matrix a, element by element, and the result written to matrix a. 

The original matrix a is lost in the process. 

Abbreviation: m s a(),b(). 

Example: 

DIM a(3,5),b(3,5) 

MAT SET a()=3 
MAT SET b()=1 
MAT PRINT a() 

PRINT STRING$(10,”-”) 

MAT PRINT b() 

PRINT STRING$(10,”-”) 

MAT SUB a(),b() 

MAT PRINT a() 

Gives: 3,3,3,3,3 

3,3,3,3,3 

3,3,3,3,3 


1 , 1 , 1 , 1,1 

1 , 1 , 1 , 1,1 

1 , 1 , 1 , 1,1 


2 , 2 , 2 , 2,2 

2,2,2,2,2 

2,2,2,2,2 
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MAT SUB a{),x is defined for all matrix (vectors). Here, the scalar x is 
subtracted from matrix x, element by element, and the result is written 
to matrix a. The original matrix a is lost in the process. 

Abbreviation: m s a(),x 

Example: 

DIM a(3,5) 

MAT SET a()=6 
MAT PRINT a() 

PRINT STRING$(10,”-") 

MAT SUB a(),5 
MAT PRINT a() 

Gives: 6,6,6,6,6 

6 , 6 , 6 , 6,6 

6 , 6 , 6 , 6,6 


5.5.5.5.5 

6 . 6 . 6 . 6.6 

5,5,5,5,5 


1 , 1 , 1 , 1,1 

1 , 1 , 1 , 1,1 

1 . 1 , 1 , 1,1 

MAT MUL a()=b()*c() is defined for matrix of an “appropriate” order. 
Arrays b and c are multiplied with each other. The result of this 
multiplication is written to matrix a. In order for the result to be 
defined, the matrix on the left (matrix b in this case) must have the 
same number of columns as the matrix on the right (c in this case) 
has rows. Array a, in this case, must have as many rows as b and as 
many columns as c, for example: 

DIM a(2,2),b(2,3),c(3,2) 

Arrays are multiplied as “row by column”, i.e. element a(i.j) is 
obtained by multiplying the elements in the ith row of matrix b with the 
elements in the jth column of matrix c, element by element, and then 
adding up the individual products. 

Abbreviation: m a()=b()*c() 
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Example: 

DIM a(2,2),b(2,3),c(3,2) 
MAT SET b()=1 
DATA 1,2,-3,4,5,-1 
MAT READ c() 

MAT PRINT b(),5,1 
PRINT STRING$(18,"-”) 
MAT PRINT c(),5,1 
PRINT STRING$(18,”-”) 
MAT MUL a()=b()*c() 
MAT PRINT a(),5,1 

Gives: 1.0, 1.0, 1.0 

1 . 0 , 1 . 0 , 1.0 


1 . 0 , 2.0 
-3.0, 4.0 
5.0, -1.0 


3.0, 5.0 
3.0, 5.0 

With vectors instead of matrix, MAT MUL a()=b()*c() results in the 
dyadic (or external) product of two vectors. 

Example: 

DIM a(3,3),b(3),c(3) 

DATA 1,2,-3,4,5,-1 
MAT READ b() 

MAT READ c() 

MAT PRINT b(),5,1 
PRINT STRING$(18,”-”) 

MAT PRINT c(),5,1 
PRINT STRING$(18,”-”) 

MAT MUL a()=b()*c() 

MAT PRINT a(),5,1 
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Gives: 1.0, 2.0, -3.0 


4.0. 5.0, -1.0 


4.0, 5.0, -1.0 
8 . 0 , 10 . 0 , - 2.0 
-12.0,-15.0, 3.0 

MAT MUL x=a()*b() is only defined for vectors with an equal number 
of elements. The result x is the scalar product (the so-called interior 
product) of vectors a and b. The scalar product of two vectors is 
defined as the sum of n products a(i)*b(i),i=1.n. 

Abbreviation: m x=a()*b(). 

Example: 

DIM b(3),C(3) 

DATA 1,2,-3,4,5,-1 
MAT READ b{) 

MAT READ c() 

MAT PRINT b(),5,1 
PRINT STRING$(18,”-”) 

MAT PRINT c(),5,1 
PRINT STRING$(18,”-’’) 

MAT MUL x=b()*c() 

PRINT x 

Gives: 1.0, 2.0, -3.0 


4.0, 5.0, -1.0 


17.0 

MAT MUL x=a()*b()*c() is defined for qualified Vectors a and c as well 
as qualified Matrix b(). 

Abbreviation: m x=a{)*b()*c(). 

Example: 


DIM a(2),b(2,3),c(3) 
DATA 1,2,-3,4,5 
MAT READ a() 

MAT READ c() 
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MAT SET b()=i 
MAT PRINT a(),5,1 
PRINT STRING$(18,"-’’) 
MAT PRINT b(),5,1 
PRINT STRING$(18,"-”) 
MAT PRINT c(),5,1 
PRINT STRING$(18,"-”) 
MAT MUL x=a()*b()*c() 
PRINT x 

Gives: 1.0, 2.0 


1 . 0 , 1 . 0 , 1.0 

1 . 0 , 1 . 0 , 1.0 

1 . 0 , 1 . 0 , 1.0 


3.0, 4.0, 5.0 


18.0 

MAT NORM a(),0 or MAT NORM a(),1 are defined for matrix and 
vectors. MAT NORM a(),0 normalises a matrix (a vector) by rows, MAT 
NORM a(),l by columns. This means that after a normalisation by 
rows (by columns) the sum of the squares of all elements in each row 
(column) is identical at 1. 

Abbreviation: m no a(),0 bzw. m no a(),1. 

Example: 


DIM a(10,10),b(10,10),v(10) 

DATA 1,2,3,4,5,6,7,8,9,-1 

DATA 3.2,4,-5,2.4,5.1,6.2,7.2,8.1,6,-5 

DATA -2,-5,-6,-1.2,-1.5,-6.7,4.5,8.1,3.4,10 

DATA 5,-2.3,4,5.6,12.2,18.2,14.1,16,-21 ,-13 

DATA 4.1,5.2,16.7,18.4,19.1,20.2,13.6,14.8,19.4,18.6 

DATA 15.2,-1.8,13.6,-4.9,5.4,19.8,16.4,-20.9,21.4,13.8 

DATA -3.6,6,-8.2,-9.1,4,-2.5,2,3.4,6.7,8.4 

DATA 4.7,8.3,9.4,10.5,11,19,15.4,18.9,-20,12.6 

DATA 5.3,-4.7,6.1,6.5,6.9-92,-10.8,43,5.6,9.1 

DATA 21.4,19.5,28.4,19.3,24.6,14.9,71.3,23.5,14.5,-12.3 
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CLS 

MAT READ a() 

MAT CPY b()=a{) ! Source matrix stored 
PRINT “Source matrix” 

PRINT 

MAT PRINT a(),7,2 
~INP(2) 


CLS 

MAT NORM a(),0 
PRINT 

PRINT “Row : ” 
PRINT 

MAT PRINT a(),7,2 
~INP(2) 


PRINT 

PRINT “Test : ” 

PRINT 

FOR i%=1 TO 10 

MAT XCPY v()=a(i%,1) ! Copy row a() in Vector v() 
MAT MUL x=v()*v() PRINT x’ 

NEXT i% 

PRINT 

~INP(2) 

’ Columns 
CLS 

MAT CPY a()=b() MAT NORM a(),1 

PRINT “Column 

PRINT 

MAT PRINT a(),7,2 

~INP(2) 

» 

PRINT 

PRINT “Test : ” 

PRINT 
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FOR i%=1 TO 10 

MAT CPY v()*a(1,i%) ! Copy column a() in the Vector v() 
MAT MUL x=v()*v() PRINT x' 

NEXT i% 

~INP(2) 

Gives: 


Source matrix 

1.00, 2.00, 3.00, 4.00, 5.00, 6.00, 7.00, 8.00, 9.00, -1.00 

3.20, 4.00, -5.00, 2.40, 5.10, 6.20, 7.20, 8.10, 6.00, -5.00 
-2.00, -5.00, -6.00, -1.20, -1.50, -6.70, 4.50, 8.10, 3.40, 10.00 
5.00, -2.30, 4.00, 5.60, 12.20, 18.20, 14.10, 16.00, -21.00, -13.00 
4.10, 5.20, 16.70, 18.40, 19.10, 20.20, 13.60, 14.80, 19.40, 18.60 

15.20, -1.80, 13.60, -4.90, 5.40, 19.80, 16.40, -20.90, 21.40, 13.80 
-3.60, 6.00, -8.20, -9.10, 4.00, -2.50, 2.00, 3.40, 6.70, 8.40 

4.70, 8.30, 9.40, 10.50, 11.00, 19.00, 15.40, 18.90, -20.00, 12.60 
5.30, -4.70, 6.10, 6.50, 6.90, -9.20, -10.80, 4.30, 5.60, 9.10 
21.40, 19.50, 28.40, 19.30, 24.60, 14.90, 71.30, 23.50, 14.50,-12.30 

Row: 

0.06, 0.12, 0.18, 0.24, 0.30, 0.35, 0.41, 0.47, 0.53, -0.06 
0.18, 0.23, -0.29, 0.14, 0.29, 0.36, 0.42, 0.47, 0.35, -0.29 
-0.11, -0.28, -0.34, -0.07, -0.09, -0.38, 0.26, 0.46, 0.19, 0.57 
0.12, -0.06, 0.10, 0.14, 0.30, 0.45, 0.35, 0.40, -0.52, -0.32 
0.08, 0.10, 0.33, 0.36, 0.38, 0.40, 0.27, 0.29, 0.38, 0.37 
0.32, -0.04, 0.29, -0.10, 0.11, 0.42, 0.35, -0.44, 0.45, 0.29 
-0.19, 0.32, -0.44, -0.48, 0.21, -0.13, 0.11, 0.18, 0.36, 0.45 
0.11, 0.19, 0.21, 0.24, 0.25, 0.43, 0.35, 0.43, -0.46, 0.29 
0.23, -0.21, 0.27, 0.29, 0.31, -0.41, -0.48, 0.19, 0.25, 0.40 
0.23, 0.21, 0.30, 0.21, 0.26, 0.16, 0.76, 0.25, 0.15, -0.13 

Test : 

1111111111 
Column : 

0.04, 0.08, 0.08, 0.12, 0.13, 0.14, 0.09, 0.18, 0.20, -0.03 
0.11, 0.16, -0.13, 0.07, 0.14, 0.14, 0.09, 0.18, 0.13, -0.14 
-0.07, -0.21, -0.15, -0.04, -0.04, -0.15, 0.06, 0.18, 0.07, 0.28 
0.18, -0.09, 0.10, 0.17, 0.33, 0.41, 0.18, 0.35, -0.46, -0.36 
0.14, 0.21, 0.42, 0.57, 0.51, 0.46, 0.17, 0.33, 0.42, 0.52 
0.53, -0.07, 0.35, -0.15, 0.15, 0.45, 0.21, -0.46, 0.47, 0.38 
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-0.13, 0.25, -0.21, -0.28, 0.11, -0.06, 0.03, 0.08, 0.15, 0.23 
0.17, 0.34, 0.24, 0.33, 0.30, 0.43, 0.20, 0.42, -0.44, 0.35 
0.19, -0.19, 0.15, 0.20, 0.19, -0.21, -0.14, 0.10, 0.12, 0.25 
0.75, 0.80, 0.72, 0.60, 0.66, 0.34, 0.90, 0.52, 0.32, -0.34 

Test : 

1111111111 

MAT DET x=a([i,j])[,n] calculates the determinants of a square matrix 
of the (n,n) type. The row and column offsets are preset to a(0,0) or 
a(1,1), depending on MAT BASE 0 or MAT BASE 1, assuming that 
OPTION BASE 1 is enabled. It is also possible, however, to calculate 
the determinant of a square part matrix. To do this, the row and 
column offsets of a() must be specified as i and j, and the number of 
elements in the part matrix as n. A part matrix of the (n,n) type is then 
created internally starting from the “position” ith row, jth column. 

Abbreviation: m d x=a([i,j])[,n]. 

Example: 

DIM a(10,10),b(4,4) 

DATA 1,2,3,4,5,6,7,8,9,-1 

DATA 3.2,4,-5,2.4,5.1,6.2,7.2,8.1,6,-5 

DATA -2,-5,-6,-1.2,-1.5,-6.7,4.5,8.1,3.4,10 

DATA 5,-2.3,4,5.6,12.2,18.2,14.1,16,-21,-13,3.8 

DATA 4.1,5.2,16.7,18.4,19.1,20.2,13.6,14.8,19.4,18.6 

DATA 15.2,-1.8,13.6,-4.9,5.4,19.8,16.4,-20.9,21.4,13.8 

DATA -3.6,6,-8.2,-9.1,4,-2.5,2,3.4,6.7,8.4,10.9 

DATA 4.7,8.3,9.4,10.5,11,19,15.4,18.9,-20,12.6 

DATA 5.3,-4.7,6.1,6.5,6.9-9.2-10.8,4.3,5.6,9.1 

DATA 21.4,19.5,28.4,19.3,24.6,14.9,71.3,23.5,14.5,-12.3 


CLS 

MAT READ a() 

PRINT “Source matrix" 
PRINT 

MAT PRINT a(),7,2 
PRINT 

PRINT “Determinant : 

MAT DET x=a() ! from a() 
PRINT x; 

MAT DET y=a(1,4) ,4 PRINT 
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PRINT "Determinant from a(1,4),4 : 

PRINT y 
PRINT 

PRINT “Test 
PRINT 

MAT CPY b()=a(1,4),4,4 ! Copy to b() 

MAT PRINT b(),7,2 

MAT DET z=b() ! Determinant from b() 

PRINT 
PRINT z 

Gives: 

Source Matrix 

1.00, 2.00, 3.00, 4.00, 5.00, 6.00, 7.00, 8.00, 9.00, -1.00 
3.20, 4.00, -5.00, 2.40, 5.10, 6.20, 7.20, 8.10, 6.00, -5.00 
-2.00, -5.00, -6.00, -1.20, -1.50, -6.70, 4.50, 8.10, 3.40, 10.00 
5.00, -2.30, 4.00, 5.60, 12.20, 18.20, 14.10, 16.00, -21.00, -13.00 

3.80, 4.10, 5.20, 16.70, 18.40, 19.10, 20.20, 13.60, 14.80, 19.40 

18.60, 15.20, -1.80, 13.60, -4.90, 5.40, 19.80, 16.40, -20.90, 21.40 

13.80, -3.60, 6.00, -8.20, -9.10, 4.00, -2.50, 2.00, 3.40, 6.70 
8.40, 10.90, 4.70, 8.30, 9.40, 10.50, 11.00, 19.00, 15.40, 18.90 
-20.00, 12.60, 5.30, -4.70, 6.10. 6.50, 6.90, -9.20, -10.80, 4.30 

5.60, 9.10, 21.40, 19.50, 28.40, 19.30, 24.60, 14.90, 71.30, 23.50 

Determinant : -2549840202186 

Determinant from a(l,4),4 : -57.61200000001 


Test: 


4.00, 5.00, 6.00, 7.00 
2.40, 5.10, 6.20, 7.20 
-1.20, -1.50, -6.70, 4.50 

5.60, 12.20, 18.20, 14.10 
-57.61200000001 

MAT QDET x=a([i,j])[,n] works in the same manner as MAT DET 
x = a([i,j])[,n], except that it has been optimised for speed rather than 
accuracy. Both will normally produce identical results. With “critical” 
matrix, whose determinant is close to 0, you should always use MAT 
DET, though. 

Abbreviation: M qd x=a([i,j])[,n]. 
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Example: 

DIM a(10,10) 

DATA 1.2,3,4,5,6,7.8,9,-1 

DATA 3.2,4,-5,2.4,5.1,6.2,7.2,8.1,6,-5 

DATA -2,-5,-6,-1.2,-1.5,-6.7,4.5,8.1,3.4,10 

DATA 5.-2.3,4,5.6,12.2,18.2,14.1,16,-21,-13,3.8 

DATA 4.1,5.2,16.7,18.4,19.1,20.2,13.6,14.8,19.4,18.6 

DATA 15.2,-1.8,13.6,-4.9,5.4,19.8,16.4,-20.9,21.4,13.8 

DATA -3.6,6,-8.2,-9.1,4,-2.5,2,3.4,6.7,8.4,10.9 

DATA 4.7,8.3,9.4,10.5,11,19,15.4,18.9,-20,12.6 

DATA 5.3,-4.7,6.1,6.5,6.9,-9.2,-10.8,4.3.5.6,9.1 

DATA 21.4,19.5,28.4,19.3,24.6,14.9,71.3,23.5,14.5,-12.3 

CLS 

MAT READ a() 

PRINT “Source matrix” 

PRINT 

MAT PRINT a(),7,2 
PRINT 

PRINT “Determinant with MAT DET : 

MAT DET x=a() 

PRINT x; 

PRINT 

PRINT “Determinant with MAT QDET : 

MAT DET y=a() 

PRINT y; 

PRINT 

PRINT “Deviation : ";x-y 
Gives: 

Source Matrix 

1.00, 2.00, 3.00, 4.00, 5.00, 6.00, 7.00, 8.00, 9.00, -1.00 
3.20, 4.00, -5.00, 2.40, 5.10, 6.20, 7.20, 8.10, 6.00, -5.00 
-2.00, -5.00, -6.00, -1.20, -1.50, -6.70, 4.50, 8.10, 3.40, 10.00 
5.00, -2.30, 4.00, 5.60, 12.20, 18.20, 14.10, 16.00, -21.00, -13.00 

3.80, 4.10, 5.20, 16.70, 18.40, 19.10, 20.20, 13.60, 14.80, 19.40 
18.60, 15.20, -1.80, 13.60, -4.90, 5.40, 19.80, 16.40, -20.90, 21.40 

13.80, -3.60, 6.00, -8.20, -9.10, 4.00, -2.50, 2.00, 3.40, 6.70 
8.40, 10.90, 4.70, 8.30, 9.40, 10.50, 11.00, 19.00, 15.40, 18.90 
-20.00, 12.60, 5.30, -4.70, 6.10, 6.50, 6.90. -9.20, -10.80, 4.30 
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5.60, 9.10, 21.40, 19.50, 28.40, 19.30, 24.60, 14.90, 71.30, 23.50 

Determinant with MAT DET : -2549840202186 
Determinant with MAT QDET : -2549840202186 

Deviation : 0 

MAT RANG x=a([i,j])[,n] outputs the rank of a square matrix. As with 
MAT DET or MAT QDET, you can select any row and column offset. 
The number of elements in the part matrix must be specified with n. 
This creates a part matrix of the (n.n) type internally, starting from the 
"position ith row, jth column. 

Abbreviation: m ra x=a([i,j])[,n]. 

Example: 

DIM a(5,5) 

DATA 1,2,3,4,5 
DATA 3.2,4,-5,2.4,5.1 
DATA -2,4,-5,2.4,5.1 
DATA 5-2.3,4,5.6,12.2 
DATA 4.1,5.2,16.7,18.4,19.1 

CLS 

MAT READ a() 

PRINT “Source matrix” 

PRINT 

MAT PRINT a(),7,2 
PRINT 

PRINT “Rang from a(): 

MAT RANG x=a() 

PRINT x; 

PRINT 

PRINT “Rang from a(1,2),3 : 

MAT RANG y=a(1,2),3 
PRINT y; 

PRINT 
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Gives: 

Source matrix 


1.00, 2.00, 3.00, 4.00, 5.00 
3.20, 4.00, -5.00, 2.40, 5.10 
-2.00, 4.00, -5.00, 2.40, 5.10 
5.00, -2.30, 4.00, 5.60, 12.20 
4.10, 5.20, 16.70, 18.40, 19.10 

Rang from a(): 5 

Rang from a(l,2),3 : 2 

MAT INV b()=a() is used to determine the inverses of a square matrix. 
The inverse of matrix a() is written to matrix b(), hence b() must be of 
the same type as a(). 

Abbreviation: m inv b()=a(). 

Example: 

DIM a(5,5) ,b(5,5),c(5,5) 

DATA 1,2,3,4,5 
DATA 3.2,4,-5,2.4,5.1 
DATA -2,4,-5,2.4,5.1 
DATA 5-2.3,4,5.6,12.2 
DATA 4.1,5.2,16.7,18.4,19.1 

CLS 

MAT READ a<) 

PRINT “Source matrix a() : ” 

PRINT 

MAT PRINT a(),7,2 

MAT INV b()=a() 

PRINT 

PRINT “Inverse from a() : ” 

PRINT 

MAT PRINT b().7,2 
PRINT 

PRINT “Test b()*a() = Unity matrix ? ” 

PRINT 

MAT MUL c()=b()*a() 
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MAT PRINT c(),7,2 
Gives: 

Source matrix a{) : 


1.00, 2.00, 3.00, 4.00, 5.00 
3.20, 4.00, -5.00, 2.40, 5.10 
-2.00, 4.00, -5.00, 2.40, 5.10 
5.00, -2.30, 4.00, 5.60, 12.20 
4.10, 5.20, 16.70, 18.40, 19.10 

Inverse from a() : 


0.00, 0.19, -0.19. -0.00, -0.00 
0.97, 0.02, -0.09, -0.10, -0.17 
0.71, -0.10, -0.10, -0.01, -0.12 
-1.65, 0.17, 0.11, -0.06, 0.39 
0.71, -0.12, 0.04, 0.09, -0.17 

Test b()*a() = Unity matrix ? 

1 . 00 , 0 . 00 , 0 . 00 , 0 . 00 , 0.00 
0 . 00 , 1 . 00 , 0 . 00 , 0 . 00 , - 0.00 
0 . 00 , - 0 . 00 , 1 . 00 , 0 . 00 , - 0.00 
- 0 . 00 , - 0 . 00 , - 0 . 00 , 1 . 00 , 0.00 
- 0 . 00 , 0 . 00 , 0 . 00 . 0 . 00 , 1.00 
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14. Further new commands in Version 3.5 

In addition to the commands described in Chapter 13, Version 3.5 of 
GFA BASIC also implements three commands from the field of 
combinatorics, two commands for the operation of DATA pointers, the 
PCOLOR command for the screen display, the commands GURU x, 
GURU, a new variant of the OPENW command as well as _0 to _9. 

Commands from the field of combinatorics 

These commands are: 

x=FACT(n) 

y=VARIAT(n,k) 

z=COMBIN(n,k) 

x,y,x: aexp 

n,k: iexp 

x=FACT(n) calculates the factorial (n!) of n and writes this value to 
the variable x. The factorial of an integer number is defined as the 
product of a multiplication with the first n integer numbers, with 0!=1. 

y=VARIAT(n,k) calculates the number of variations of n elements to 
the kth class without repetition, and writes this value to the variable y. 

The number of variations of n elements to the kth class without 
repetitions is defined as 

VARIAT(n,k)=n!/(n-k)! 

z=COMBIN(n,k) calculates the number of combinations of n 
elements to the kth class without repetitions and writes this value to 
the 

variable z. The number of combinations of n elements to the kth class 
without repetitions is defined as 

COMBIN(n.k) =n!/((n-k)!*k!) 

Example: 

x=FAXT(6) 

y=VARIAT(6,2) 

z=COMBIN(6,2) 
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PRINT x,y,z 
~INP(2) 

Gives: 720 30 15 

New variant of the command OPENW 

If the screen number is negative, the window is opened in the current 
screen (= top screen). 


Determining foreground and background colours 
PCOLOR foreground, background 

This command does the same as COLOR, but the PRINT command is 
used for the actual screen output. 

Example: 

PCOLOR 2,3 
PRINT TIMES 
PCOLOR 1 
PRINT DATES 
PCOLOR 0,2 
PRINT “HELLO” 


Command for the operation of DATA pointers 
DATA 


DATA- 

DATA specifies the position of the DATA pointer. DATA is 0 if the 
next READ would result in an “out of data". 

DATA- permits the setting of the DATA pointer to a value which has 
been previously determined with DATA. 
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Example: 

DIM dp%(100) 

DATA 1,2,3,4,5,6,7,8,9 
DATA 13,24,328,3242,1,0 


i%=0 

DO WHILE DATA 
dp%(i%)=_DATA 
INC i% 

READ a 
LOOP 

DEC i% 

FOR j%=i% DOWNTO 0 
_DATA=dp%(j%) 

READ a 
PRINT a 
NEXT j% 

~INP(2) 

Gives: 0 1 324232824 13 98 765432 1 

Special Variables 

_0—_9 

The commands _0 to 9 are ten special variables. They are longwords 
like %, not floating point numbers. 

These variables are only erased by the ‘NEW’ command, but not by 
CLEAR, LOAD, CHAIN, or RUN. 

These variable can be used, for example, to store AllocMem 
addresses, LibraryBase and similar items during a program’s test 
phase, and to correctly release them even with a RUN, or to preserve 
them through a CHAIN. 
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GURU x 

if x=0: no GURU check 

if x<>0: when a GURU Meditation appears (= system crash), GFA 
BASIC 

jumps to the ONERROR GOSUB routine or n error message #109 
“GURU Meditation!" is generated. 

The most important GURU numbers can be checked with the GURU 
function. 

Example: 

GURU 1 

ONERROR GOSUB ER 
~FREEmem(1000000,10) 

PROCEDURE ER 
PRINT HEX$(GURU) 

END 

RETURN 

Notes: 

The error messages #110 to #118 are the “normal" GURUS $2 to $A. 

In compiled programs (Version 3.5) it is NOT possible to execute a 
“RESUME NEXT” or “RESUME LABEL”, if a GURU has caused an 
ONERROR GOSUB call. 

It is always safest to terminate a program as soon as possible 
following error message #109 (“GURU Meditation!"). The GURUS $2 
to $A (Error messages #110 to #118) are not as dangerous and do 
not normally pose problems. 

The GURU check only works if the system is capable of continuing 
program execution. GURUS are really system problems and nothing 
to do with GFA BASIC! 
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